Iniciar sessãoAgendar apresentação

Capítulo 2.9

A imagem de disco do instalador

Arranque um servidor físico ou uma máquina virtual a partir da imagem do instalador do Nexus e esta instalará o sistema operativo, o k3s, o cert-manager e o Nexus sem rede, verificando cada ficheiro antes de ser utilizado.

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

17 minutos de leitura

O gabinete do capitão do porto no cais leste de Harrow tem um servidor, não tem internet e não há ninguém no local que administre Kubernetes. Ainda assim, Tomás Reilly precisava do Nexus a funcionar nele. Gravou a imagem numa pen USB (Universal Serial Bus), colocou ao lado uma segunda pen pequena com quatro linhas de definições e iniciou o servidor. Uma hora depois, o ecrã mostrava o endereço da consola e as três linhas a adicionar ao ficheiro hosts. Não escreveu um único comando de Kubernetes.

Essa é a função da imagem de disco do instalador. Grava um sistema operativo mínimo no disco do servidor e, no primeiro arranque, verifica cada ficheiro que contém com a chave de lançamento da Adverant, instala o k3s sem rede, importa todas as imagens, instala o cert-manager e o Nexus, e verifica se todos os pods estão em execução. Cada passo para com um motivo identificado no exato momento em que algo corre mal. Não há execução em modo degradado nem qualquer palavra-passe predefinida.

As duas imagens

Cada lançamento é disponibilizado em dois tipos de imagem, para duas arquiteturas de processador: amd64 e arm64.

Ficheiro O que contém Quem pode transferir
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Apenas o instalador: o sistema operativo, o k3s v1.33.6+k3s1, o cert-manager v1.21.3 e o instalador de primeiro arranque. Funciona para qualquer uma das edições e não contém imagens do Nexus. Qualquer pessoa, a partir de downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso O mesmo instalador com o pacote offline dessa edição adicionado como uma segunda partição com a etiqueta NEXUS-BUNDLE. Um único suporte instala tudo. Community: qualquer pessoa. Enterprise: apenas a partir da sua conta Adverant

<arch> é amd64 ou arm64, e <edition> é community ou enterprise.

O instalador procura sempre apenas um sistema de ficheiros com a etiqueta NEXUS-BUNDLE. Na imagem tudo-em-um, trata-se da partição na própria imagem. Com a imagem apenas do instalador, fornece o pacote num segundo disco ou pen com essa etiqueta, o que é útil quando instala vários locais a partir de uma única pen de instalação e altera apenas o pacote. O Capítulo 2.10, Instalação isolada de rede (air-gapped), descreve o pacote.

As imagens Enterprise e os pacotes Enterprise nunca são anónimos. Pode transferi-los a partir da sua conta Adverant em https://account.adverant.ai, na página de Transferências, junto à sua licença. As imagens e os pacotes Community são públicos.

Dois desenhos de discos encontram-se lado a lado. O da esquerda, "imagem apenas do instalador", tem uma partição com a etiqueta "instalador do sistema operativo, k3s, cert-manager, instalador de primeiro arranque" e, ao lado, uma pen USB separada com a etiqueta "NEXUS-BUNDLE: o pacote offline da edição". O da direita, "imagem tudo-em-um", tem a mesma primeira partição e uma segunda partição no mesmo disco com a etiqueta "NEXUS-BUNDLE". Por baixo de ambos, uma pequena pen USB tem a etiqueta "NEXUS-SEED: seed.yaml, e licence.json para Enterprise", com uma nota "opcional para Community". Setas a partir das três etiquetas apontam para baixo para uma única caixa, "o primeiro arranque encontra cada um pela respetiva etiqueta".
A imagem apenas do instalador e a imagem tudo-em-um, e onde o primeiro arranque encontra cada parte.

De que é construída a imagem

O sistema operativo baseia-se no Debian 13 e não é uma imagem oficial do Debian. Contém o sistema base do Debian e nada mais: sem pacotes adicionais, sem ambiente gráfico e sem espelho (mirror). O k3s traz o seu próprio ambiente de execução de contentores e configuração de rede. A cadeia de arranque (shim, GRUB, o kernel e o ramdisk inicial) é, byte a byte, a que o Debian distribui, pelo que uma máquina com Secure Boot ativo a inicia como qualquer instalador Debian.

Duas compilações do mesmo lançamento produzem imagens idênticas, byte a byte, e o lançamento não é publicado até que isso aconteça. Os pacotes de código-fonte Debian para cada binário na imagem são publicados ao lado desta como nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, na mesma lista de somas de verificação (checksums).

Verificar a transferência antes de a gravar

O diretório de imagens em downloads.adverant.ai contém as imagens, um ficheiro SHA256SUMS que abrange todos os ficheiros publicados e SHA256SUMS.sigstore.json, a assinatura sobre essa lista efetuada com a chave de lançamento da Adverant. Obtenha a chave pública de lançamento separadamente, guarde-a como release.pub e verifique a sua impressão digital conforme descrito no capítulo 2.4, Obter e verificar um lançamento.

  1. Verifique a assinatura na lista de somas de verificação. Não existe registo de transparência para os lançamentos do Nexus, pelo que o parâmetro que ignora a consulta ao registo é obrigatório.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Verifique a imagem que transferiu em relação à lista:
grep nexus-alpha-community-1.0.0-alpha.1-amd64.iso SHA256SUMS | sha256sum -c -
nexus-alpha-community-1.0.0-alpha.1-amd64.iso: OK

Num Mac, utilize shasum -a 256 -c - em vez de sha256sum -c -.

  1. Grave a imagem numa pen USB com a ferramenta que utiliza habitualmente, ou anexe-a à máquina virtual como um disco ótico.

O k3s publica somas de verificação para os seus ficheiros de lançamento e nenhuma assinatura, pelo que os ficheiros do k3s dentro da imagem são verificados em relação às somas de verificação que o k3s publica, a partir da mesma origem que os ficheiros. Tudo o que a Adverant construiu está assinado.

Pacotes divididos em partes

Um pacote que transporte numa pen separada tem vários gigabytes. Alguns sistemas de ficheiros, entre os quais o FAT (File Allocation Table), não suportam ficheiros de 4 GiB ou mais, pelo que os ficheiros do pacote são publicados em partes de 2047 MiB que cabem em qualquer pen. Volte a juntar as partes por ordem e verifique o ficheiro unido em relação ao respetivo .sha256 antes de o utilizar.

O hardware necessário

O primeiro arranque verifica a máquina antes de tocar no que quer que seja e recusa-se a avançar quando a máquina é demasiado pequena.

Verificação A base mínima Quando é verificado
Arquitetura A da própria imagem: uma imagem amd64 em amd64, arm64 em arm64 Primeiro arranque
Memória 16 GiB Primeiro arranque
Disco de destino Exatamente um disco vazio com pelo menos 64 GB, ou o disco indicado na seed Antes de o sistema operativo ser gravado
Espaço livre em / 50 GB após o sistema operativo estar instalado Primeiro arranque
Relógio Não anterior à data em que a imagem foi compilada Primeiro arranque

Estes são valores mínimos absolutos, não uma recomendação. Com as predefinições do chart, só os volumes do Nexus somam 142 GiB, pelo que um disco de 64 GB passa no instalador mas enche em poucos dias. Utilize o que um nó único deve ter: 8 vCPU (unidades de processamento central virtuais), 32 GiB de memória e um SSD (unidade de estado sólido) de 250 GB. Quatro vCPU, 16 GiB e 200 GB são suficientes para uma avaliação.

A verificação do relógio existe porque o servidor não tem rede e, portanto, não tem serviço de hora durante a instalação. Os certificados e as assinaturas são verificados em função do relógio. Se o relógio de hardware da máquina estiver atrasado em relação à data de compilação da imagem, o primeiro arranque para e pede-lhe que o acerte. Acerte-o na configuração do firmware e volte a arrancar.

Servidores físicos (bare metal) e máquinas virtuais

A imagem arranca em firmware UEFI (Unified Extensible Firmware Interface), tanto em servidores físicos como em máquinas virtuais. Instala o gestor de arranque (boot loader) no caminho de suporte amovível, bem como no caminho habitual, para que uma VM (máquina virtual) sem entradas de arranque guardadas o continue a encontrar após o primeiro reinício. Atribua a uma VM a memória e o disco indicados na tabela acima, um disco virtual vazio e a imagem como um CD.

O instalador escolhe o disco de destino segundo uma regra estrita e nunca escolhe "o primeiro disco".

  • Ignora o suporte a partir do qual arrancou.
  • Ignora discos amovíveis, a menos que a seed indique um.
  • Ignora qualquer disco que já tenha uma tabela de partições, de qualquer tipo.
  • Ignora discos abaixo de 64 GB e indica-o na consola.
  • Instala apenas quando resta exatamente um disco.

Num servidor com dois discos vazios, o instalador para e pede-lhe que escolha. A escolha é feita indicando o disco na seed, com wipe: true, que é a única forma de o instalador alguma vez gravar num disco que já tenha partições.

O volume NEXUS-SEED

A seed é um pequeno volume, habitualmente uma pen USB, com um sistema de ficheiros com a etiqueta NEXUS-SEED e um ficheiro seed.yaml na sua raiz. O instalador monta-o apenas para leitura, lê as definições e volta a montá-lo com permissão de escrita apenas mesmo no final, para lhe deixar a palavra-passe do sistema operativo.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Chave O que define Quando está em falta
domain O domínio da instalação. O instalador deriva os três anfitriões (hosts) a partir dele: console.<domain>, api.<domain> e auth.<domain>. Solicitado na consola do servidor
adminEmail O email da pessoa que será o primeiro administrador Solicitado na consola do servidor
edition community ou enterprise. Quando definido, tem de corresponder à edição do pacote. Obtido a partir do pacote
timeout Quanto tempo podem demorar o cert-manager e a instalação do Nexus, como uma duração tal como 30m ou 1h 30m
time A hora atual em UTC, no formato apresentado pela mensagem do relógio (2026-11-14T09:00:00Z), para uma máquina cujo relógio de hardware não possa ser acertado ou não retenha a definição. Uma máquina offline não tem um servidor de hora a quem perguntar. É utilizado o relógio de hardware
disk O disco de destino, como /dev/<name>, utilizado apenas em conjunto com wipe: true A regra de disco vazio acima
wipe true permite que o instalador apague o disco indicado por disk Nenhum disco é alguma vez apagado

Para a edição Enterprise, coloque o ficheiro de licença no mesmo volume como licence.json. Sem ele, o primeiro arranque para no passo da seed e indica que a licença está em falta. A edição Community não precisa de licença e, para a Community, toda a seed é opcional: o instalador pede o domínio e o email na consola e prossegue.

O instalador lê cada linha como key: value no início da linha. Escreva uma chave por linha, no nível superior, sem aspas e sem indentação. Um valor entre aspas é lido com as respetivas aspas.

No primeiro arranque, o instalador pede também na consola o guardião (custodian) do armazenamento de chaves: a metade pública de uma chave age, age1..., criada na própria máquina do guardião com age-keygen -o custodian.key. O armazenamento de chaves sela as suas chaves de recuperação com ela. O Capítulo 2.8, Instalações numa única máquina, explica o conceito de guardiões. O guardião mantém a metade privada offline e em segurança: sem ela, ninguém consegue remover o selo do armazenamento de chaves após um reinício.

O que acontece, desde que se liga a máquina até ao endereço da consola

Fase um: o sistema operativo

A imagem arranca num instalador Debian autónomo (unattended). Não configura uma rede, não utiliza um espelho (mirror) nem instala qualquer pacote além do sistema base. Define o fuso horário para UTC (Tempo Universal Coordenado), desativa o início de sessão como root e cria um utilizador, nexus, cuja palavra-passe fica bloqueada. Escolhe o disco de destino segundo a regra acima e grava um disco GPT (tabela de partições de identificador único global) com uma partição de sistema EFI (Extensible Firmware Interface) e um sistema de ficheiros raiz ext4, sem swap.

No final, copia o instalador do Nexus para o novo sistema, verifica cada ficheiro copiado em relação à lista de somas de verificação da imagem e ativa um serviço de primeiro arranque. Se algum ficheiro copiado não coincidir, para nesse ponto. De seguida, ejeta o suporte e reinicia.

Fase dois: o primeiro arranque

No primeiro arranque, o serviço nexus-install é executado uma vez. Cada passo é apresentado na consola do servidor e no journal, e regista-se como concluído, para que uma nova tentativa comece a partir do primeiro passo que ainda não o esteja. O serviço como um todo pode ser executado durante um máximo de quatro horas antes de o systemd o parar, o que dá margem para um disco lento e uma hora de espera pela pen do pacote.

  1. Verificação prévia (Preflight). A arquitetura, o relógio, a memória e o espaço livre em disco, conforme indicado na tabela acima.
  2. Carga útil (Payload). Os próprios ficheiros do instalador: a assinatura na sua lista de somas de verificação com a chave de lançamento que transporta e, de seguida, cada ficheiro em relação a essa lista.
  3. Seed. Lê seed.yaml e pede na consola o que estiver em falta.
  4. Pacote (Bundle). Encontra o volume com a etiqueta NEXUS-BUNDLE e monta-o apenas para leitura. Se não existir nenhum, apresenta waiting-for-bundle e aguarda até uma hora para que o anexe. De seguida, executa a verificação completa do pacote, terminando em VERIFY-BUNDLE PASS, com a chave de lançamento que transporta, antes de qualquer coisa ser importada. Um pacote Enterprise requer licence.json na seed, e a edição da seed tem de coincidir com a do pacote.
  5. k3s. Instala o k3s v1.33.6+k3s1 a partir dos próprios ficheiros da imagem com as transferências desativadas e aguarda até dez minutos para que o nó fique Ready. De seguida, remove o arquivo de imagens air-gap do k3s, para que as imagens não sejam importadas novamente em cada arranque.
  6. Importação (Import). Importa todas as imagens verificadas do pacote, bem como as imagens do cert-manager, para o armazenamento de contentores do nó. Nada é alguma vez transferido a partir de um registo (registry).
  7. cert-manager e, de seguida, Nexus. Instala o cert-manager v1.21.3 e, de seguida, o chart do Nexus a partir do pacote, ambos dentro do timeout da seed.
  8. Aceitação (Acceptance). Verifica se todos os pods estão no estado Running e se todos os Jobs de hook foram concluídos.
  9. Credencial (Credential). Atribui ao utilizador nexus do sistema operativo uma nova palavra-passe aleatória, mostra-a uma vez na consola e grava-a em nexus-os-password.txt no volume da seed, quando é possível escrever no volume.

A verificação do pacote no passo 4 é o mesmo script que executa manualmente no capítulo 2.10, Instalação isolada de rede (air-gapped), e apresenta as mesmas linhas:

  1 SHA256SUMS OK files=<n>
  2 SHA256SUMS signature OK
  3 images signed + SBOM-attested: <n>
  4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
  5 coverage OK rendered=<n> lock=<n>
  6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>

A linha 3 contabiliza as imagens que possuem uma assinatura válida e uma SBOM (lista de materiais de software) assinada, a lista do que cada imagem contém. As contagens (<n>) dependem da edição. O que importa é a última linha.

A instalação grava valores no formato atual do chart: global.domain e os três nomes hosts.* a partir do domínio da seed, e keys.custody.recipients a partir do guardião que indicou na consola. Instala a partir do próprio chart e imagens do pacote, pelo que o lançamento no disco é exatamente o lançamento que foi verificado.

Uma cadeia horizontal de nove caixas: Verificação prévia (Preflight), Carga útil (Payload), Seed, Pacote (Bundle), k3s, Importação (Import), cert-manager e Nexus, Aceitação (Acceptance), Credencial (Credential). Por baixo de cada caixa, uma pequena etiqueta vermelha mostra o que a faz parar: "memória, disco, relógio, arquitetura", "assinatura ou soma de verificação", "sem domínio ou email; sem licença para Enterprise", "sem NEXUS-BUNDLE em 1 h; VERIFY-BUNDLE FAIL", "nó não está Ready em 10 min", "uma imagem não é importada", "helm install falha dentro do tempo limite", "um pod não está em execução, um Job não está concluído", e nada por baixo de Credencial. Uma seta de retorno a partir de cada caixa para o início da cadeia tem a etiqueta "nexus-install retry retoma no primeiro passo não concluído".
O primeiro arranque da imagem do instalador, um passo após o outro, cada um capaz de parar a instalação.

As últimas linhas na consola

Quando todos os passos são concluídos com sucesso, a consola mostra uma vez a palavra-passe do sistema operativo e o endereço a abrir:

nexus-install: OS login: user nexus, password <shown-once>  (shown once; change it with passwd)
nexus-install: DONE: https://console.harrow.example  (add to /etc/hosts: 10.20.4.15 console.harrow.example api.harrow.example auth.harrow.example)

Aponte a palavra-passe ou obtenha-a a partir da pen da seed e, de seguida, inicie sessão como nexus e altere-a com passwd. Ninguém, incluindo a Adverant, conhece uma palavra-passe predefinida para esta máquina, porque não existe nenhuma.

O endereço na linha hosts é o do próprio servidor. Sem DNS (Domain Name System) no cais, o Tomás adicionou essa única linha ao ficheiro hosts de cada portátil que iria utilizar a consola. Num local com DNS, adicione antes registos para os três nomes.

Pronto, ou ainda não
Pronto, ou ainda não
Após a instalação, a lista de prontidão inclui um teste de tráfego de saída, para que um operador possa demonstrar que nada tentou sair na última hora.

Após a instalação

A instalação está por reclamar. Ninguém pode iniciar sessão até que alguém a reclame num navegador, comparando a impressão digital da instalação com a que o servidor apresenta. O Capítulo 2.12, A primeira execução, aborda a reclamação, o primeiro administrador e a passkey. O primeiro administrador deve ser a pessoa cujo email consta na seed.

O ficheiro kubeconfig do próprio nó encontra-se em /etc/rancher/k3s/k3s.yaml, podendo ser lido apenas pelo root. Para trabalhar no cluster a partir de uma estação de trabalho, nexusctl kubeconfig imprime-o, conforme descrito no capítulo 2.8, Instalações numa única máquina.

As atualizações chegam da mesma forma que a instalação: um lançamento num suporte assinado, verificado em relação à chave já instalada no servidor e nunca em relação a uma chave que o disco traga consigo. O Capítulo 2.10, Instalação isolada de rede (air-gapped), descreve essa verificação.

Reclamar esta instalação
Reclamar esta instalação
A página de reclamação que se segue à instalação. A impressão digital é apresentada em oito grupos de quatro, para comparar com a consola do servidor linha a linha.

Se isto falhar

Cada falha apresenta nexus-install: FAILED <step>: <what is missing> na consola e grava o mesmo em /var/lib/nexus/install.state. Corrija a causa e execute novamente a instalação a partir do primeiro passo que não esteja concluído:

sudo nexus-install retry
Mensagem O que significa O que fazer
FAILED preflight: payload is for arm64, this machine is amd64 Arrancou a imagem da outra arquitetura. Utilize a imagem para a arquitetura desta máquina.
FAILED preflight: memory 11 GiB, need >= 16 GiB A máquina tem menos do que o mínimo exigido. Adicione memória ou atribua mais à VM.
FAILED preflight: free disk 38 GB on /, need >= 50 GB O sistema de ficheiros raiz é demasiado pequeno. Instale num disco maior.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed O relógio de hardware está atrasado em relação à data em que o instalador foi compilado. Acerte o relógio no firmware, ou indique time em seed.yaml, e tente novamente.
FAILED payload: SHA256SUMS signature does not verify Os próprios ficheiros do instalador não correspondem ao que a Adverant assinou. Pare. Transfira novamente a imagem e verifique-a antes de a gravar.
FAILED seed: the installation domain and the first administrator e-mail are required Nem a seed nem a consola os forneceram. Adicione-os a seed.yaml ou responda às solicitações.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) O pacote é Enterprise e a seed não tem licença. Coloque licence.json no volume da seed.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Nenhum pacote foi anexado a tempo. Anexe a pen do pacote e tente novamente.
FAILED bundle: the bundle does not verify with this installer's release key A verificação do pacote não terminou em VERIFY-BUNDLE PASS. A sua própria saída, acima da mensagem, indica o passo. Pare. Não utilize esse pacote. Obtenha um novo.
FAILED bundle: the seed asks for enterprise, the bundle is community A seed e o pacote não coincidem. Corrija edition na seed ou traga o pacote correto.
FAILED k3s: node not Ready within 10 min O k3s não iniciou. Verifique o journal para o k3s e tente novamente.
FAILED nexus: helm install nexus O chart não foi instalado dentro do tempo limite. Consulte kubectl -n nexus get pods,jobs, aumente timeout na seed se a máquina for lenta e tente novamente.
FAILED acceptance: pods not ready Alguns pods não estão em execução após a instalação. A mensagem indica até cinco. Leia os respetivos eventos, corrija e tente novamente.
FAILED acceptance: jobs not complete: <jobs> Um Job de hook não terminou. Leia o registo (log) do Job indicado com kubectl -n nexus logs job/<name>, corrija o que este reporta e tente novamente.

Antes de o sistema operativo ser gravado, a escolha do disco também pode parar a instalação. A respetiva mensagem começa por nexus select-disk: REFUSED:. A mais comum é found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Indique o disco na seed e volte a arrancar.

Uma falha na verificação do pacote é o erro que deve ser levado a sério. Significa que os ficheiros no disco não são os ficheiros que a Adverant assinou, ou que um ficheiro foi adicionado. O instalador ainda não importou nada nesse momento, pelo que o servidor permanece inalterado. Guarde o disco para a sua equipa de segurança.