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

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.
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.
- 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 SHA256SUMSVerified OK
- 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 -.
- 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.
- 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.
- 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.
- Seed. Lê
seed.yamle pede na consola o que estiver em falta. - Pacote (Bundle). Encontra o volume com a etiqueta
NEXUS-BUNDLEe monta-o apenas para leitura. Se não existir nenhum, apresentawaiting-for-bundlee aguarda até uma hora para que o anexe. De seguida, executa a verificação completa do pacote, terminando emVERIFY-BUNDLE PASS, com a chave de lançamento que transporta, antes de qualquer coisa ser importada. Um pacote Enterprise requerlicence.jsonna seed, e a edição da seed tem de coincidir com a do pacote. - 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.
- 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).
- 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
timeoutda seed. - Aceitação (Acceptance). Verifica se todos os pods estão no estado Running e se todos os Jobs de hook foram concluídos.
- Credencial (Credential). Atribui ao utilizador
nexusdo sistema operativo uma nova palavra-passe aleatória, mostra-a uma vez na consola e grava-a emnexus-os-password.txtno 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.
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.
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.
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.

