Versão 1.0.0-alpha.1mais recente
Capítulo 2.10
Instalação isolada da rede (air-gapped)
Transporte um pacote offline assinado para uma instalação sem internet, verifique-o contra uma chave que trouxe separadamente, carregue-o no seu próprio registo e instale. Licenças, atualizações e listas de revogação também atravessam o isolamento manualmente.
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 rede de operações da Harrow Port Authority não tem rota para a internet, por lei e por conceção. O tráfego de navios, os planos de atracação e as retenções alfandegárias residem todos nela, e nada nela pode comunicar para o exterior. Quando Tomás Reilly instalou o Nexus lá, cada byte chegou num disco que um estafeta trouxe até à portaria, e cada byte foi verificado dentro das instalações antes de ser utilizado por qualquer sistema.
Este capítulo trata dessa instalação. Obtém um pacote offline assinado, verifica-o com uma chave que lhe chegou por uma rota diferente, copia as respetivas imagens para o seu próprio registo, verifica-as novamente aí e instala o chart com o nome do seu registo nos valores. Depois vêm as coisas que uma instalação isolada (air-gapped) faz manualmente e que uma instalação ligada obtém gratuitamente: k3s e cert-manager sem transferência, atualizações em suporte físico, licenças através de uma troca offline e listas de revogação que importa por si próprio.
O que contém o pacote offline
Um pacote é uma edição de uma versão de lançamento, sob a forma de um arquivo tar não comprimido com um ficheiro de soma de verificação (checksum) ao lado: nexus-alpha-1.0.0-alpha.1-enterprise.tar e nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256. Os pacotes Community são públicos em downloads.adverant.ai. Os pacotes Enterprise provêm da sua conta Adverant em https://account.adverant.ai, junto à sua licença, e nunca de forma anónima.
Depois de descompactado, tem este aspeto:
nexus-alpha-1.0.0-alpha.1-enterprise/
release/facts.json the release facts: version, edition, architectures, key fingerprint
release/facts-gaps.json the release facts the build couldn't record, each with its reason
release/images.lock.json every image by digest: index, per platform, its SBOMs
release/source-offer.json the sources of every copyleft data-tier image
release/source-offer.sha256 a checksum for each of those source files
images/<svc>/ one cosign save layout per image
charts/nexus-1.0.0-alpha.1.tgz the Helm chart
sbom/<edition>/<svc>-<arch>.spdx.json
source-offer/ the source files themselves
docs/INSTALL-AIRGAP.md
docs/example-values.yaml
docs/RELEASE-NOTES.md
SHA256SUMS a checksum for every file above
SHA256SUMS.sigstore.json the signature over SHA256SUMS, made with the release key
Cada diretório images/<svc>/ é o que o cosign save escreve. Contém o índice de imagens e as imagens de ambas as plataformas, linux/amd64 e linux/arm64, com a assinatura cosign, uma atestação SPDX SBOM (lista de materiais de software) para cada plataforma e uma atestação de proveniência, todas criadas com a chave de lançamento da Adverant. As mesmas SBOM encontram-se em sbom/ como ficheiros simples, para que uma equipa de segurança as possa ler sem o cosign.
A camada de dados inclui software copyleft: PostgreSQL com PostGIS e Neo4j Community Edition, entre outros. O pacote transporta o código-fonte de todas as imagens da camada de dados que fornece, e release/source-offer.json indica-o para cada imagem. Um pacote que fornecesse um binário copyleft sem o respetivo código-fonte não chega a ser compilado.
release/facts.json indica a versão de lançamento, a edição, as arquiteturas e a impressão digital (fingerprint) da chave de lançamento com que o pacote foi assinado, como sha256:<hex>.
A chave pública viaja separadamente
O pacote nunca contém a chave que o verifica. Um pacote que transportasse a sua própria chave poderia ser substituído, com chave e tudo, por qualquer pessoa, e todas as verificações continuariam a passar. O script de verificação recusa uma chave que se encontre dentro do diretório do pacote.
Obtenha a chave pública de lançamento uma única vez, numa máquina ligada à internet, a partir de https://downloads.adverant.ai/nexus/1.0.0-alpha.1/. Guarde-a como release.pub. A sua impressão digital é o SHA-256 do ficheiro:
sha256sum release.pubCompare esse valor com a impressão digital que a Adverant publica e com a que consta nas notas de lançamento que recebeu por um canal separado. O Capítulo 2.4, Obter e verificar uma versão de lançamento, contém os detalhes. Em seguida, transporte o release.pub para as instalações, por uma rota diferente da do pacote, se possível, e guarde-o lá. A equipa de Tomás guarda-o na partilha de ficheiros da rede de operações com uma nota da data em que deu entrada. Todas as versões de lançamento posteriores são verificadas contra essa chave instalada, e nunca contra algo que um disco traga consigo.
Verificar o pacote
verify-bundle.sh é o script que verifica um pacote, publicado com cada versão de lançamento. A imagem de disco do instalador executa o mesmo script no primeiro arranque. Necessita do cosign v3, helm v4 e sha256sum ou shasum. Não lê nada de nenhuma rede e não necessita de Python, pelo que é executado tanto num nó instalador simples como numa estação de trabalho.
- Verifique o arquivo tar contra a respetiva soma de verificação e, em seguida, descompacte-o:
sha256sum -c nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256
tar -xf nexus-alpha-1.0.0-alpha.1-enterprise.tar- Execute a verificação com a chave que trouxe para as instalações:
./verify-bundle.sh nexus-alpha-1.0.0-alpha.1-enterprise release.pubUm terceiro argumento indica um ficheiro de valores para as verificações do chart. Sem ele, o script utiliza o docs/example-values.yaml do pacote.
- Leia a última linha, que tem de ser
VERIFY-BUNDLE PASSantes de avançar mais.
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>
O script para na primeira verificação que falhar. Eis o que cada uma faz.
| Passo | O que verifica |
|---|---|
| 1 | Cada ficheiro listado em SHA256SUMS corresponde à respetiva soma de verificação e não está presente nenhum ficheiro que a lista omita. Um ficheiro extra introduzido falha tão certamente como um ficheiro alterado. |
| 2 | SHA256SUMS.sigstore.json é uma assinatura válida sobre SHA256SUMS feita pela chave que indicou. Com os passos 1 e 2 juntos, cada byte no pacote é o byte que a Adverant assinou. |
| 3 | Para cada diretório de imagem: o resumo (digest) do índice da imagem está em release/images.lock.json; existe uma assinatura cosign cujo sujeito é esse resumo exato e que é verificada contra a sua chave; cosign verify e cosign verify-attestation --type spdxjson passam ambos na estrutura guardada. |
| 4 | helm lint --strict passa no chart com os valores de exemplo, ou com os seus. |
| 5 | Cada imagem no ficheiro de bloqueio (lock) está guardada em images/, e cada imagem que o chart processa é um resumo no ficheiro de bloqueio. Nada do que o chart instala provém de outro local. |
| 6 | Quando o ficheiro de bloqueio contém imagens da camada de dados, release/source-offer.json está completo, indica cada uma delas e todos os ficheiros de código-fonte que lista estão presentes com a soma de verificação correta. |
O passo 3 verifica a própria assinatura, por resumo, além de executar cosign verify. A razão deve-se ao próprio comportamento do cosign: cosign verify numa estrutura guardada também termina com o código 0 quando a estrutura contém apenas uma atestação feita pela chave e nenhuma assinatura. O script não aceita isso.
Se isto falhar
Uma falha termina com VERIFY-BUNDLE FAIL step=<k> <why>.
| Última linha | O que significa | O que fazer |
|---|---|---|
step=0 the public key must come from outside the bundle |
A chave que indicou está dentro do diretório do pacote. | Utilize a chave que trouxe separadamente. |
step=1 checksum mismatch |
Um ficheiro foi alterado depois de a lista ter sido criada ou ficou danificado em trânsito. | Copie novamente o pacote a partir do suporte físico original e volte a verificar. |
step=1 files not covered by SHA256SUMS |
Foi adicionado um ficheiro ao pacote. | Trate o suporte físico como não fidedigno. Não instale a partir dele. |
step=2 SHA256SUMS signature does not verify |
A lista de somas de verificação não está assinada pela chave de lançamento que possui. | Pare. Comunique o facto à sua equipa de segurança e peça um novo suporte físico à Adverant. |
step=3 image <svc>: ... |
A assinatura ou a atestação SBOM de uma imagem está em falta ou não passa na verificação. | Pare, tal como no passo 2. |
step=4, step=5 |
O chart ou a respetiva lista de imagens não é consistente. | Peça um novo pacote à Adverant. |
step=6 ... |
A disponibilização de código-fonte está incompleta. | Peça um novo pacote à Adverant. |
A falha dos passos 2 e 3 é o caso para o qual toda esta conceção existe. Significa que os ficheiros não são os que a Adverant assinou. Guarde o suporte físico para a sua equipa de segurança.
Carregar as imagens no seu próprio registo
Os seus nós extraem imagens a partir de um registo dentro das instalações. O de Harrow é registry.harrow.example. Cada imagem do Nexus fica sob o caminho nexus/ nesse registo, porque o chart faz referência a cada imagem como <global.imageRegistry>/nexus/<svc>@<digest>.
- Inicie sessão no seu registo com a ferramenta que utiliza normalmente, para que o
cosignpossa enviar (fazer push) para lá. - A partir do interior do diretório do pacote, carregue cada imagem e verifique-a novamente na sua nova localização:
REG=registry.harrow.example
jq -r '.images[] | "\(.svc) \(.index)"' release/images.lock.json | while read -r svc digest; do
cosign load --dir "images/$svc" "$REG/nexus/$svc"
cosign verify --key release.pub --insecure-ignore-tlog=true "$REG/nexus/$svc@$digest" > /dev/null \
&& cosign verify-attestation --key release.pub --insecure-ignore-tlog=true --type spdxjson "$REG/nexus/$svc@$digest" > /dev/null \
&& echo "verified $svc"
doneO cosign load transporta a assinatura e todas as atestações juntamente com a imagem, pelo que a cópia do registo é verificada contra a mesma chave. A verificação feita aqui é a que conta para o seu cluster: prova que o que os seus nós vão extrair é o que a Adverant assinou.
verified nexus-alpha
verified nexus-auth
verified nexus-postgres
...
Cada imagem no ficheiro de bloqueio deve imprimir uma linha verified. Uma linha em falta significa que o carregamento ou a verificação dessa imagem falhou, e o respetivo erro é impresso imediatamente acima.
Não existe registo de transparência (transparency log) para as versões de lançamento do Nexus, pelo que --insecure-ignore-tlog=true é necessário em cada verificação. A chave de lançamento constitui toda a raiz de confiança. Sem esta opção, o cosign recusa com not enough verified log entries from transparency log: 0 < 1.
Instalar a partir do seu registo
O ficheiro de valores para uma instalação isolada (air-gapped) difere de uma instalação ligada numa única linha: global.imageRegistry indica o seu registo.
# harrow-prod-values.yaml (Helm values)
global:
imageRegistry: registry.harrow.example
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: enterprise
enterprise:
enabled: true
tls:
mode: existing
existingSecret: harrow-public-tls
storage:
className: harrow-ssd
keys:
installationName: harrow-port
custody:
recipients:
- "<custodian-one-age-recipient>"
- "<custodian-two-age-recipient>"As entradas <custodian-...-age-recipient> são as linhas age1... públicas das pessoas que detêm as chaves de recuperação do armazenamento de chaves. O Capítulo 2.8, Instalações numa única máquina, explica como cada pessoa cria uma. harrow-ssd é a classe de armazenamento própria de Harrow: coloque a sua, ou omita storage.className para utilizar a predefinição do cluster.
- Execute a verificação prévia (preflight) no cluster com este ficheiro, conforme descreve o capítulo 2.5, Verificação prévia com o nexusctl.
- Instale a partir do chart do pacote e omita
--wait.
helm install nexus charts/nexus-1.0.0-alpha.1.tgz -n nexus --create-namespace \
-f harrow-prod-values.yaml --timeout 45m
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900shelm install --wait entra em impasse (deadlock) com este chart: um hook pós-instalação atribui a cada serviço a respetiva palavra-passe da base de dados, e --wait retém os hooks até que os serviços estejam ativos. O Capítulo 2.8, Instalações numa única máquina, tem o ciclo que também aguarda pelos StatefulSets.
Com nexusctl, a mesma instalação é nexusctl install --context <kube-context> --values harrow-prod-values.yaml.
Nada no chart comunica para fora do namespace, exceto o DNS (Domain Name System), a API (interface de programação de aplicações) do Kubernetes para revisões de tokens e qualquer endereço que liste em networkPolicy.externalEgressCIDRs, que está vazio por predefinição. Nenhuma telemetria sai da instalação, e telemetry.enabled não pode ser definido para outro valor senão false. Para IA (inteligência artificial) num local sem internet, a organização liga o seu próprio servidor de modelos compatível com OpenAI dentro das instalações, indicado em ai.localProvider.baseUrl; o capítulo 2.14, Fornecedores e modelos de IA, aborda este tema.
A licença não é um valor do chart. Deve importá-la após a instalação, conforme descrito abaixo.
k3s e cert-manager sem transferência
Se o Nexus for instalado num cluster k3s construído por si, o k3s também tem de ser instalado sem rede. A imagem de disco do instalador faz isto por si (capítulo 2.9, A imagem de disco do instalador). Manualmente, em cada nó:
- Transfira os ficheiros de lançamento do k3s v1.33.6+k3s1 para a sua arquitetura: o binário
k3s(k3s-arm64em arm64),install.sh,k3s-airgap-images-<arch>.tar.zstesha256sum-<arch>.txt. O k3s publica somas de verificação para estes ficheiros e nenhuma assinatura. Verifique cada ficheiro contrasha256sum-<arch>.txte deixe claro junto da sua equipa de segurança que se trata de uma soma de verificação da mesma origem, e não de uma assinatura. - Coloque o binário e as imagens de sistema onde o k3s os procura e instale com as transferências desativadas:
sudo install -m 0755 k3s /usr/local/bin/k3s
sudo mkdir -p /var/lib/rancher/k3s/agent/images
sudo cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
sudo INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC="--write-kubeconfig-mode=0600" sh install.sh
sudo k3s kubectl wait --for=condition=Ready node --all --timeout=600sO cert-manager v1.21.3 é um pré-requisito: a própria CA (autoridade de certificação) do chart é um emissor do cert-manager. Transfira o chart do cert-manager, cert-manager-v1.21.3.tgz, e as respetivas imagens. Do lado ligado à internet, verifique as imagens com a chave própria do projeto cert-manager antes de atravessarem para as instalações:
cosign verify --signature-digest-algorithm sha512 --insecure-ignore-tlog=true \
--key cert-manager-pubkey-2021-09-20.pem quay.io/jetstack/<image>@<digest>Dentro das instalações, importe as imagens para o armazenamento de contentores de cada nó sob os nomes que o chart do cert-manager pede, quay.io/jetstack/cert-manager-<name>:v1.21.3, e depois verifique-as e instale:
sudo k3s ctr -n k8s.io images import --all-platforms cert-manager-images.tar
sudo k3s ctr -n k8s.io images ls -q | grep cert-manager
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10m--wait é adequado para o cert-manager. É apenas o Nexus que não o deve ter.
Atualizações e novas partes chegam em suportes assinados
Uma instalação isolada também é atualizada a partir de um disco. Na consola, Importar de suporte físico nas páginas Esta instalação carrega uma versão de lançamento a partir de um disco trazido para as instalações. Verifica a soma de verificação de cada ficheiro, depois a assinatura contra a chave de lançamento já instalada no local — nunca uma chave que o disco traga — e, em seguida, se a versão de lançamento é mais recente do que a que está em execução. A importação apenas copia e verifica. As pessoas continuam a trabalhar na versão em execução e nada muda até que opte por atualizar.
A partir da linha de comandos, a mesma versão de lançamento entra com nexusctl:
nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar
nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarplan mostra o que irá mudar e não altera nada. apply faz primeiro uma cópia de segurança e depois atualiza. O Capítulo 2.15, Dia dois: operar o Nexus, aborda as atualizações na íntegra.
Quando a assinatura de um disco não corresponde, a importação é recusada com MEDIA_SIGNATURE_INVALID. Nada é carregado ou copiado e a versão em execução continua a funcionar. A página indica que verificações passaram, onde parou e a chave que esperava ao lado da chave que encontrou. Guarde o disco para a sua equipa de segurança e peça um novo à Adverant.
Os componentes Enterprise que uma licença ativa chegam da mesma forma numa instalação isolada: no disco de lançamento, através de Importar de suporte físico, antes de os ativar. Cada componente é verificado contra a chave de lançamento da Adverant antes de ser ativado, pelo que nunca copia um binário manualmente para o cluster.
Licenças sem internet
Uma instalação ligada recebe a sua licença automaticamente. Uma instalação isolada troca ficheiros com a Adverant manualmente, através da troca offline.
- As páginas de licença da consola criam um pequeno ficheiro de pedido de licença. A instalação assina-o com a sua própria chave, para que a Adverant possa saber que instalação fez o pedido.
- Alguém leva o ficheiro numa pen USB para um computador que esteja online, inicia sessão na conta Adverant em
https://account.adverant.aie carrega-o na página Troca offline. - Trazem o ficheiro de licença de volta da mesma forma.
- Importe-o. Na consola, abra Licença e o que desbloqueia e prima Importar uma nova licença. A partir da linha de comandos:
nexusctl licence import harrow-port-licence.jsonA licença é verificada offline, dentro das instalações, contra as chaves da Adverant. A Adverant assina cada licença com duas chaves independentes, e ambas as assinaturas têm de passar na verificação.
A mesma troca transporta a declaração anual de utilização para o exterior. Contém apenas contadores (lugares, dispositivos, grupos de funcionalidades) e o administrador lê-a linha a linha em Declaração de utilização para a Adverant antes de sair.
| Código | Estado | O que significa |
|---|---|---|
LICENCE_SIGNATURE_INVALID |
422 | O ficheiro não é uma licença assinada pela Adverant, ou um byte foi alterado após a assinatura. Nada muda. |
LICENCE_OTHER_INSTALLATION |
409 | A licença é genuína, mas foi emitida para outra instalação. Peça uma emitida para o id desta instalação. |
LICENCE_CLOCK_BEHIND_FLOOR |
409 | O relógio indica uma hora anterior à última hora que esta instalação registou. Atrasar o relógio não reativa uma licença expirada. |
LICENCE_REVOKED |
403 | A Adverant retirou a licença através de uma revogação assinada. Os componentes Enterprise deixam de ser disponibilizados; a edição Community e a exportação mantêm-se. |
O Capítulo 2.13, Licenças, aborda os estados, o período de tolerância e a renovação.
As listas de revogação são importadas manualmente
Quando a Adverant retira uma licença, publica uma lista de revogação assinada. A lista é cumulativa: cada uma contém todas as licenças retiradas antes dela. Uma instalação ligada toma conhecimento disso. Uma instalação isolada só toma conhecimento quando alguém importa a lista; por isso, traga a lista mais recente juntamente com cada disco de lançamento e importe-a através da importação de revogações da instalação nas páginas de licença, ou do endereço /api/v1/installation/licence/revocations no anfitrião de início de sessão.
Isto funciona nos dois sentidos. Uma instalação isolada que nunca importe uma lista nunca saberá que uma licença foi revogada, incluindo uma licença assinada por uma chave que mais tarde se descobriu estar comprometida. Importar a lista é a única forma de essa informação atravessar o isolamento.
O pacote selado soberano: nexus-airgap
Algumas instalações soberanas pretendem uma versão de lançamento como um único ficheiro selado e assinado cujo próprio manifesto proíba o acesso à rede. Para elas existe um segundo formato, o pacote selado, e a respetiva ferramenta, nexus-airgap, do pacote @adverant/nexus-sovereign. Instale a ferramenta a partir do registo de pacotes da Adverant, separadamente de qualquer pacote que esta vá verificar. Um pacote não pode atestar a sua própria validade.
O pacote selado é um único arquivo tarball assinado. O respetivo manifesto é assinado com Ed25519 e lista um SHA-256 para cada ficheiro. A ferramenta tem quatro verbos.
| Verbo | O que faz |
|---|---|
nexus-airgap bundle |
Constrói um pacote selado a partir de um diretório preparado (staged) e assina o respetivo manifesto. |
nexus-airgap verify --bundle <file> --trusted-key <pem> --profile <profile> |
Verifica a assinatura contra a chave fidedigna, recalcula o hash de cada ficheiro, recusa qualquer ficheiro que o manifesto não liste e recusa um pacote cuja regra de rede não seja a lista de permissões vazia com tráfego de agentes apenas local. Não altera nada. |
nexus-airgap install |
Verifica e, em seguida, executa o plano de instalação por ordem: carregar as imagens, aplicar os manifestos, executar as migrações, inicializar as competências (skills), aprovisionar as chaves. |
nexus-airgap open |
Abre a exportação encriptada opcional do pacote com o guardião de chaves próprio das instalações, que numa instalação isolada é o chip TPM (Trusted Platform Module) da máquina. |
Verifique antes de mais nada:
nexus-airgap verify --bundle nexus-alpha-1.0.0-alpha.1.tar.gz \
--trusted-key release.pub --profile airgap --keep-staging > verify.json
jq '{ok, bundleId, profile, artifactsVerified}' verify.json--keep-staging mantém a cópia verificada e descompactada e identifica-a como stagingDir no resultado, para que trabalhe a partir do que foi verificado.
Se a verificação falhar com BUNDLE_INTEGRITY_VIOLATION, um ficheiro dentro do pacote foi alterado depois de ter sido assinado. Pare aí. A ferramenta tem uma opção --no-strict que ignora a verificação de ficheiros não listados. Não a utilize numa versão de lançamento.
O dia em que chega o disco seguinte
Tomás mantém uma pequena lista de verificação colada no interior do armário da portaria, e vale a pena copiá-la. Verifique o .sha256 do arquivo tar. Execute o verify-bundle.sh com a chave instalada e leia a última linha. Importe a lista de revogação mais recente. Só então, e apenas nessa altura, importe a versão de lançamento a partir do suporte físico e planeie a atualização. Um disco que falhe em qualquer um destes passos volta para dentro do envelope, etiquetado, para a equipa de segurança, e nada na rede foi alterado.


