バージョン 1.0.0-alpha.1最新
第 2.10 章
エアギャップ環境へのインストール
署名済みのオフラインバンドルをインターネットのないサイトに持ち込み、別途持ち込んだキーと照合して検証し、独自のレジストリにロードしてインストールします。ライセンス、アップデート、および失効リストも手動でギャップを越えて持ち込みます。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

Harrow Port Authorityの運用ネットワークには、法律上および設計上、インターネットへの経路がありません。船舶交通、バース計画、税関保留はすべてその上に存在し、そこから外部へ通信することは一切許されていません。Tomás ReillyがそこにNexusをインストールした際、すべてのバイトはクーリエが守衛所に届けたディスクで到着し、すべてのバイトは何かに使用される前にサイト内でチェックされました。
この章はそのインストールについてです。署名されたオフラインバンドルを入手し、別の経路で届いたキーでそれをチェックし、そのイメージを独自のレジストリにコピーし、そこでもう一度チェックし、valuesにレジストリの名前を指定してチャートをインストールします。次に、接続されたサイトでは自動で行われるものの、エアギャップサイトでは手作業で行う事柄が続きます。ダウンロードなしのk3sとcert-manager、メディアによるアップデート、オフライン交換を通じたライセンス、そして自分でインポートする失効リストです。
オフラインバンドルの内容
バンドルとは、1つのリリースの1つのエディションであり、非圧縮のtarとそれに添えられたチェックサムファイル(nexus-alpha-1.0.0-alpha.1-enterprise.tarおよびnexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256)です。Communityバンドルはdownloads.adverant.aiで公開されています。Enterpriseバンドルはhttps://account.adverant.aiのAdverantアカウントからライセンスと並んで提供され、匿名で提供されることは決してありません。
展開すると、次のようになります。
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
各images/<svc>/ディレクトリは、cosign saveが書き出すものです。ここにはイメージインデックスと両方のプラットフォームのイメージ(linux/amd64とlinux/arm64)が保持されており、cosign署名、各プラットフォームのSPDX SBOM(ソフトウェア部品表)アテステーション、およびプロビナンス(来歴)アテステーションが付属しています。これらはすべてAdverantリリースキーで作成されています。同じSBOMがプレーンファイルとしてsbom/に置かれているため、セキュリティチームはcosignなしでそれらを読むことができます。
データ層には、PostGIS付きのPostgreSQLやNeo4j Community Editionなどのコピーレフトソフトウェアが含まれています。バンドルは出荷するすべてのデータ層イメージのソースを保持しており、release/source-offer.jsonには各イメージについてその旨が記載されています。ソースなしでコピーレフトバイナリを出荷するようなバンドルはビルドされません。
release/facts.jsonは、リリース、エディション、アーキテクチャ、およびバンドルの署名に使用されたリリースキーのフィンガープリントをsha256:<hex>として指定します。
公開鍵の別経路での移動
バンドルには、それをチェックするキーは決して含まれません。自身のキーを保持するバンドルは、誰によってもキーごと置き換えられる可能性があり、それでもすべてのチェックに合格してしまいます。検証スクリプトは、バンドルディレクトリ内にあるキーを拒否します。
接続されたマシンで、https://downloads.adverant.ai/nexus/1.0.0-alpha.1/からリリース公開キーを一度だけ取得します。それをrelease.pubとして保存します。そのフィンガープリントはファイルのSHA-256です。
sha256sum release.pubそれをAdverantが公開しているフィンガープリント、および別のチャネルで受け取ったリリースノート内のフィンガープリントと比較します。詳細は第2.4章「リリースの取得と検証」にあります。次に、可能であればバンドルとは別の経路でrelease.pubをサイト内に持ち込み、そこに保管します。Tomásのチームは、持ち込まれた日付のメモとともに運用ネットワークのファイル共有にそれを保管しています。以降のすべてのリリースは、ディスクが持ち込むものに対してではなく、そのインストールされたキーに対してチェックされます。
バンドルの検証
verify-bundle.shは各リリースとともに公開される、バンドルをチェックするスクリプトです。インストーラーディスクイメージは初回起動時に同じスクリプトを実行します。これにはcosign v3、helm v4、およびsha256sumまたはshasumが必要です。どのネットワークからも何も読み取らず、Pythonも必要としないため、ワークステーションと同様にベアインストーラーノードでも実行できます。
- tarをそのチェックサムと照合してから展開します。
sha256sum -c nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256
tar -xf nexus-alpha-1.0.0-alpha.1-enterprise.tar- 持ち込んだキーを使用して検証を実行します。
./verify-bundle.sh nexus-alpha-1.0.0-alpha.1-enterprise release.pub3番目の引数は、チャートチェック用のvaluesファイルを指定します。これがない場合、スクリプトはバンドルのdocs/example-values.yamlを使用します。
- 先に進む前に、最後の行を読み、それが
VERIFY-BUNDLE PASSであることを確認してください。
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>
スクリプトは最初に失敗したチェックで停止します。各チェックが行うことは次のとおりです。
| ステップ | チェック内容 |
|---|---|
| 1 | SHA256SUMSにリストされているすべてのファイルがそのチェックサムと一致し、リストから漏れているファイルが存在しないこと。仕込まれた余分なファイルは、変更されたファイルと同様に確実に失敗します。 |
| 2 | SHA256SUMS.sigstore.jsonが、指定したキーによるSHA256SUMSに対する有効な署名であること。ステップ1と2を合わせることで、バンドル内のすべてのバイトがAdverantが署名したバイトとなります。 |
| 3 | すべてのイメージディレクトリについて:イメージのインデックスダイジェストがrelease/images.lock.jsonにあること、その正確なダイジェストをサブジェクトとするcosign署名があり、キーに対して検証されること、保存されたレイアウトでcosign verifyとcosign verify-attestation --type spdxjsonの両方が合格すること。 |
| 4 | サンプルのvalues、または独自のvaluesを使用したチャートでhelm lint --strictが合格すること。 |
| 5 | ロック内のすべてのイメージがimages/に保存されており、チャートがレンダリングするすべてのイメージがロック内のダイジェストであること。チャートがインストールするものは、他のどこからも来ません。 |
| 6 | ロックがデータ層イメージを保持している場合、release/source-offer.jsonが完全であり、それらすべてを指定し、リストされているすべてのソースファイルが正しいチェックサムで存在すること。 |
ステップ3では、cosign verifyを実行するだけでなく、ダイジェストによって署名自体もチェックします。その理由はcosign自体の動作にあります。保存されたレイアウトに対するcosign verifyは、レイアウトがキーによるアテステーションのみを保持し、署名がない場合にも0で終了します。スクリプトはそれを受け入れません。
これが失敗する場合
失敗はVERIFY-BUNDLE FAIL step=<k> <why>で終わります。
| 最後の行 | 意味 | 対処法 |
|---|---|---|
step=0 the public key must come from outside the bundle |
指定したキーがバンドルディレクトリ内にあります。 | 別途持ち込んだキーを使用してください。 |
step=1 checksum mismatch |
リストが作成された後にファイルが変更されたか、輸送中に破損しました。 | 元のメディアからバンドルを再度コピーして、再チェックしてください。 |
step=1 files not covered by SHA256SUMS |
バンドルにファイルが追加されました。 | そのメディアを信頼できないものとして扱ってください。そこからインストールしないでください。 |
step=2 SHA256SUMS signature does not verify |
チェックサムリストが、保有しているリリースキーで署名されていません。 | 停止してください。セキュリティチームに報告し、Adverantに新しいメディアを依頼してください。 |
step=3 image <svc>: ... |
イメージの署名またはSBOMアテステーションが欠落しているか、検証されません。 | ステップ2と同様に停止してください。 |
step=4, step=5 |
チャートまたはそのイメージリストの整合性が取れていません。 | Adverantに新しいバンドルを依頼してください。 |
step=6 ... |
ソースの提供が不完全です。 | Adverantに新しいバンドルを依頼してください。 |
ステップ2と3の失敗は、この設計全体が存在する理由そのもののケースです。これは、ファイルがAdverantが署名したものではないことを意味します。セキュリティチームのためにメディアを保管しておいてください。
独自のレジストリへのイメージのロード
ノードはサイト内のレジストリからイメージをプルします。Harrowのものはregistry.harrow.exampleです。チャートは各イメージを<global.imageRegistry>/nexus/<svc>@<digest>として参照するため、すべてのNexusイメージはそのレジストリ内のパスnexus/の下に配置されます。
cosignがプッシュできるように、通常使用しているツールでレジストリにログインします。- バンドルディレクトリ内からすべてのイメージをロードし、新しい場所で再度検証します。
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"
donecosign loadはイメージとともに署名とすべてのアテステーションを運ぶため、レジストリのコピーは同じキーに対して検証されます。ここでの検証はクラスターにとって重要なものであり、ノードがプルするものがAdverantが署名したものであることを証明します。
verified nexus-alpha
verified nexus-auth
verified nexus-postgres
...
ロック内のすべてのイメージは、1行のverifiedを出力するはずです。行が欠落している場合は、そのイメージのロードまたはチェックが失敗したことを意味し、そのエラーはすぐ上に出力されます。
Nexusリリースには透明性ログがないため、すべてのチェックで--insecure-ignore-tlog=trueが必要です。リリースキーが信頼のルート全体となります。このフラグがないと、cosignはnot enough verified log entries from transparency log: 0 < 1を出して拒否します。
レジストリからのインストール
エアギャップインストール用のvaluesファイルは、接続されたものと1行だけ異なります。global.imageRegistryにレジストリを指定します。
# 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>"<custodian-...-age-recipient>のエントリは、キーストアのリカバリキーを保持する人々の公開age1...行です。それぞれがどのように作成するかについては、第2.8章「単一マシンへのインストール」で説明しています。harrow-ssdはHarrow独自のストレージクラスです。独自のものを指定するか、クラスターのデフォルトを使用する場合はstorage.classNameを省略してください。
- 第2.5章「nexusctlによるプリフライト」で説明されているように、このファイルを使用してクラスターに対してプリフライトを実行します。
- バンドルのチャートからインストールし、
--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=900sこのチャートではhelm install --waitはデッドロックします。ポストインストールフックが各サービスにデータベースパスワードを付与しますが、--waitはサービスが起動するまでフックを保留するためです。第2.8章「単一マシンへのインストール」には、StatefulSetも待機するループが記載されています。
nexusctlを使用する場合、同じインストールはnexusctl install --context <kube-context> --values harrow-prod-values.yamlになります。
チャート内のものは、DNS(ドメインネームシステム)、トークンレビュー用のKubernetes API(アプリケーションプログラミングインターフェース)、およびnetworkPolicy.externalEgressCIDRsにリストしたアドレス(デフォルトでは空)を除き、ネームスペースの外部には一切到達しません。テレメトリがインストール環境から出ることはなく、telemetry.enabledはfalse以外には設定できません。インターネットのないサイトでのAI(人工知能)については、組織はサイト内で独自のOpenAI互換モデルサーバーを接続し、ai.localProvider.baseUrlで指定します。これについては第2.14章「AIプロバイダーとモデル」で説明しています。
ライセンスはチャートの値ではありません。以下で説明するように、インストール後にインポートします。
ダウンロードなしの k3s と cert-manager
自分で構築したk3sクラスターにNexusを導入する場合、k3sもネットワークなしでインストールする必要があります。インストーラーディスクイメージはこれを代行します(第2.9章「インストーラーディスクイメージ」)。各ノードで手作業で行う場合は次のとおりです。
- お使いのアーキテクチャ用のk3s v1.33.6+k3s1リリースファイル(
k3sバイナリ(arm64ではk3s-arm64)、install.sh、k3s-airgap-images-<arch>.tar.zst、およびsha256sum-<arch>.txt)を持ち込みます。k3sはこれらのファイルのチェックサムを公開していますが、署名はありません。各ファイルをsha256sum-<arch>.txtと照合し、これが署名ではなく同じオリジンからのチェックサムであることをセキュリティチームに明確に伝えてください。 - バイナリとシステムイメージをk3sが探す場所に配置し、ダウンロードをオフにしてインストールします。
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=600scert-manager v1.21.3は前提条件です。チャート独自のCA(認証局)はcert-managerのissuerです。cert-managerのチャート、cert-manager-v1.21.3.tgz、およびそのイメージを持ち込みます。接続されている側で、持ち込む前にcert-managerプロジェクト独自のキーでイメージをチェックします。
cosign verify --signature-digest-algorithm sha512 --insecure-ignore-tlog=true \
--key cert-manager-pubkey-2021-09-20.pem quay.io/jetstack/<image>@<digest>サイト内で、cert-managerチャートが要求する名前(quay.io/jetstack/cert-manager-<name>:v1.21.3)の下で、すべてのノードのコンテナストアにイメージをインポートし、チェックしてインストールします。
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 10mcert-managerには--waitが適切です。これを指定してはいけないのはNexusだけです。
アップデートと新しいパーツの署名済みメディアでの到着
エアギャップサイトはアップグレードもディスクから行います。コンソールの「This installation(このインストール)」ページにあるImport from media(メディアからインポート)は、サイトに持ち込まれたディスクからリリースをロードします。すべてのファイルのチェックサムをチェックし、次にディスクが持ち込んだキーではなくサイトにすでにインストールされているリリースキーに対して署名をチェックし、さらにリリースが実行中のものより新しいことをチェックします。インポートはコピーとチェックのみを行います。人々は実行中のリリースで作業を続け、アップグレードを選択するまで何も変更されません。
コマンドラインからは、同じリリースが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は何が変更されるかを表示し、何も変更しません。applyは最初にバックアップを取ってからアップグレードします。第2.15章「Day 2:Nexusの運用」でアップグレードについて詳しく説明しています。
ディスクの署名が一致しない場合、インポートはMEDIA_SIGNATURE_INVALIDで拒否されます。何もロードまたはコピーされず、実行中のリリースがそのまま実行され続けます。ページには、どのチェックに合格し、どこで停止したか、そして見つかったキーと並んで予期していたキーが表示されます。セキュリティチームのためにディスクを保管し、Adverantに新しいものを依頼してください。
ライセンスによって有効になるEnterpriseパーツも、エアギャップサイトでは同じ方法で提供されます。つまり、有効にする前に、リリースディスクから「Import from media(メディアからインポート)」を通じて提供されます。各パーツは有効になる前にAdverantリリースキーに対してチェックされるため、手作業でバイナリをクラスターにコピーすることは決してありません。
インターネットなしのライセンス
接続されたインストール環境は、それ自体でライセンスを受け取ります。エアギャップ環境は、オフライン交換を通じて、手作業でAdverantとファイルを交換します。
- コンソールのライセンスページで、小さなライセンスリクエストファイルを作成します。どのインストール環境が要求したかをAdverantが判別できるよう、インストール環境は独自のキーでそれに署名します。
- 誰かがUSBメモリでそのファイルを持ち出してオンラインのコンピューターに運び、
https://account.adverant.aiでAdverantアカウントにサインインし、Offline exchange(オフライン交換)ページでアップロードします。 - 同じ方法でライセンスファイルを持ち帰ります。
- それをインポートします。コンソールでLicence and what it unlocks(ライセンスとロック解除される機能)を開き、Import a new licence(新しいライセンスをインポート)を押します。コマンドラインからは次のとおりです。
nexusctl licence import harrow-port-licence.jsonライセンスはサイト内でオフラインで、Adverantのキーに対してチェックされます。Adverantはすべてのライセンスに2つの独立したキーで署名し、両方の署名が検証される必要があります。
同じ交換方法で、年間の使用状況ステートメントも持ち出されます。これにはカウンター(シート数、デバイス数、機能グループ)のみが保持されており、管理者は持ち出す前にUsage statement for Adverant(Adverant向け使用状況ステートメント)で1行ずつ確認します。
| コード | ステータス | 意味 |
|---|---|---|
LICENCE_SIGNATURE_INVALID |
422 | ファイルがAdverantが署名したライセンスではないか、署名後にバイトが変更されました。何も変更されません。 |
LICENCE_OTHER_INSTALLATION |
409 | ライセンスは本物ですが、別のインストール環境向けに発行されたものです。このインストール環境のID向けに発行されたものを依頼してください。 |
LICENCE_CLOCK_BEHIND_FLOOR |
409 | クロックが、このインストール環境が確認した最新の時刻よりも前を示しています。クロックを戻しても、期限切れのライセンスは復活しません。 |
LICENCE_REVOKED |
403 | Adverantが署名付きの失効によってライセンスを取り消しました。Enterpriseパーツの提供は停止され、Communityとエクスポートは維持されます。 |
第2.13章「ライセンス」では、状態、猶予期間、および更新について説明しています。
失効リストは手作業でインポートします
Adverantはライセンスを取り消すと、署名付きの失効リストを公開します。このリストは累積的であり、各リストにはそれ以前に取り消されたすべてのライセンスが含まれています。接続されたインストール環境はそれを自動的に認識します。エアギャップ環境は誰かがリストをインポートしたときにのみ認識するため、各リリースディスクとともに最新のリストを持ち込み、ライセンスページの失効インポート、またはサインインホストの/api/v1/installation/licence/revocationsアドレスを通じてインポートしてください。
これは両刃の剣です。リストを決してインポートしないエアギャップインストール環境は、後に危殆化したことが判明したキーで署名されたライセンスを含め、ライセンスが失効したことを決して認識しません。リストをインポートすることが、その知らせがギャップを越える唯一の方法です。
ソブリン封印バンドル:nexus-airgap
一部のソブリンサイトでは、自身のマニフェストでネットワークアクセスを禁止する、1つの封印され署名されたファイルとしてのリリースが求められます。そのようなサイト向けに、2つ目のフォーマットである封印バンドル(sealed bundle)と、パッケージ@adverant/nexus-sovereignから提供されるそのツールnexus-airgapがあります。チェック対象となるバンドルとは別に、Adverantのパッケージレジストリからツールをインストールしてください。バンドルがそれ自体の正当性を保証することはできません。
封印バンドルは、単一の署名付きtarballです。そのマニフェストはEd25519で署名されており、すべてのファイルのSHA-256がリストされています。ツールには4つのサブコマンド(verb)があります。
| サブコマンド | 行うこと |
|---|---|
nexus-airgap bundle |
ステージングされたディレクトリから封印バンドルをビルドし、そのマニフェストに署名します。 |
nexus-airgap verify --bundle <file> --trusted-key <pem> --profile <profile> |
信頼されたキーに対して署名をチェックし、すべてのファイルを再ハッシュし、マニフェストにリストされていないファイルを拒否し、ネットワークルールが「空の許可リストとローカルのみのエージェントトラフィック」ではないバンドルを拒否します。何も変更しません。 |
nexus-airgap install |
検証してから、インストール計画を順番に実行します(イメージのロード、マニフェストの適用、マイグレーションの実行、スキルのシード、キーのプロビジョニング)。 |
nexus-airgap open |
サイト独自のキーカストディアン(エアギャップサイトではマシンのTPM(Trusted Platform Module)チップ)を使用して、バンドルのオプションの暗号化されたエクスポートを開きます。 |
何よりもまず検証します。
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は検証済みで展開されたコピーを保持し、出力内でそれをstagingDirとして指定します。
検証がBUNDLE_INTEGRITY_VIOLATIONで失敗した場合、バンドル内のファイルが署名後に変更されています。そこで停止してください。ツールには、リストされていないファイルのチェックをスキップする--no-strictスイッチがあります。リリースに対しては使用しないでください。
次のディスクが到着する日
Tomásは守衛所のキャビネットの内側に短いチェックリストをテープで貼っており、これは真似する価値があります。tarの.sha256をチェックする。インストールされているキーでverify-bundle.shを実行し、最後の行を読む。最新の失効リストをインポートする。その後、その後にのみ、メディアからリリースをインポートし、アップグレードを計画する。これらのステップのいずれかに失敗したディスクは、セキュリティチームのためにラベルを貼って封筒に戻され、ネットワーク上のものは何も変更されません。


