サインインブリーフィングを予約

第 2.28 章

拡張機能のリリース

プラグインやパックが正常なビルドから実行ユニットへどのように配備され、またどのように撤回されるかを解説します。バージョン、リリースレビュー、チャネルとインストール、署名、変更承認、配信IDレコード、マイグレーション、ロールバック、バージョンの廃止について説明します。

このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

読了時間 18 分

Cold chain 0.4.0 は、私たちのリリースの中で、前のリリースよりも多くを要求した最初のリリースでした。冷凍コンテナ(リーファー)のアラートのために、メール送信と外部アドレス 1 件を追加したのです。ビルドはグリーンで、テストは 3 つの合成ブランチすべてで合格しましたが、それでも 2 人がその要求内容を読み、3 人目がアドレスを承認するまで、2 日間 dev スペースにとどまりました。Nexus でのリリースとは本来そのようなものです。コードは簡単な部分であり、エビデンスと承認こそがリリースなのです。

この章では、グリーンのビルドから全ユニットでバージョンが稼働するまでのすべてと、そこから戻る方法を扱います。dev スペースからステージング、パイロットユニット、全ユニットへと進む昇格パスそのものは、第 2.24 章「カスタムバーティカルをエンドツーエンドで構築する」で紹介しており、ここではそのゲートを繰り返しません。すべての前提となるルールが 1 つあります。デプロイはインストール環境のリリースチャネルを通じてのみ行います。緊急の修正のための裏口はなく、稼働中のイメージを手作業で編集する人もいません。

バージョン

パックのリリースでは 3 つのバージョン番号が動きます。これらを頭の中で区別しておくと役に立ちます。

対象 記載場所 例 ルール
プラグイン nexus.manifest.json の version 0.4.0 セマンティックバージョン。-rc.1 のようなプレリリースのサフィックスを使用できます
パック pack.json の version 0.4.0 パックのレンズ、用語、クラスターとともに変わります
ナレッジモデル モデル自身のバージョン 1.3 から 1.4 グラフ変更リクエストによってのみ変わります

開発ビルドには、ステージングに到達するまでサフィックス 0.4.0-dev が付きます。プラグインとパックを一緒に出荷する場合は、両者のバージョンを同じにしてください。そうすれば、エビデンスがどの番号に属するかをめぐる議論を、リリースレビューのたびに避けられます。

ほかの 2 つのバージョンは、選ぶものではなく固定されるものです。パックのテンプレートバージョン(Cold chain では domain-pack@1.6.0)はパックの作成時に固定され、レビュー済みの変更としてのみ変わります。SDK(ソフトウェア開発キット)は範囲ではなく正確なバージョンでインストールされるため、同じビルドは翌月も同じ結果になります。

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Skills Engine のスキルにもバージョンがありますが、その振る舞いは異なります。公開された各バージョンは固定されており、live、canary、shadow はバージョンに付けるラベルです。元に戻す操作はラベルを移動するだけで、すでに実行中の処理は開始したときのバージョンで完了します。

レビューを依頼する前に:マニフェスト

マニフェストと権限のページでは、このリリースが宣言している内容を前回のリリースと比較します。対象はスコープ、ストア、外部送信先アドレス、サンドボックスプロファイルです。レビューを依頼する前にこのページを読んでください。レビュー担当者が何を受け入れるよう求められるのかが、正確にわかります。

マニフェストと権限
マニフェストと権限
Cold chain 0.4.0 が 0.3.2 に対して宣言している内容です。拡大としてマークされた 2 行、つまりメール送信と外部アドレス 1 件、そして 2 人のレビュー担当者が受け入れるまでリリースは dev スペースから先に進まないことを示すプレートに注目してください。

以前にマニフェストで宣言した内容より多くを要求するリリースは、2 人のレビュー担当者が拡大されたマニフェストを受け入れるまで、MANIFEST_SCOPE_WIDENED とともにその場に保留されます。外部アドレスには、顧客側で外部アドレスを所管する担当者の承認も必要です。この承認には期限があり、私たちの場合は 12 か月でした。先に進む方法は 2 つあります。該当する行を削除するか、レビューを依頼するかです。ページには両方のボタンがあります。

このページのすべての行は、レビューされるだけでなく実行時にも強制されます。各ツール呼び出しは宣言されたスコープと照合され、外部アドレスは一覧に記載されていない限りブロックされ、サンドボックスプロファイルはそれ以外のネットワークを一切許可しません。宣言していないものにアクセスしようとするプラグインは拒否され、唯一の解決策は、それを宣言した新しいリリースを出すことです。

リリースレビュー

リリースレビューのページは、1 つのリリースのエビデンスを、作成者ではないレビュー担当者のために 1 つの表にまとめます。

リリースレビュー
リリースレビュー
2 人目のレビュー担当者から見た Cold chain 0.4.0 の画面で、エビデンスの表、スコープの差分、コメントが表示されています。右側のプレートに注目してください。作成者は自分のリリースを承認できません。
エビデンス 0.4.0 での結果
テスト 3 つの合成ブランチで 66 件中 66 件
品質チェック ドキュメントとコードが一致している
ポリシー 各レンズは絞り込むのみ。個人に関するフィールドはデフォルトでオフ
署名 イメージとパッケージはパイプラインによって署名済み
スコープの差分 メール送信と外部アドレス 1 件を承認付きで追加
互換性 テストに使用したプラットフォームのバージョンとベースパックのバージョン
モデルの変更 グラフ変更リクエストのドライラン:1,284 件のリンクの名前を変更、削除はなし

表の下には、変更に関するコメントと来歴が表示されます。どのパイプラインが、どの変更から構築したか、イメージのダイジェスト、テンプレートです。レビュー担当者はパスキーで承認します。作成者ではない 2 人のレビュー担当者が承認すると、パイプラインがリリースをステージングに移します。作成者がレビュー担当者として数えられることはなく、試みても NEEDS_SECOND_PERSON で拒否されます。レビューリクエストは 3 日で失効します。

レビュー担当者の質問には、チャットウィンドウではなくコメントで回答してください。私たちのレビューでは、コンプライアンス責任者が請求金額を商業情報に分類した理由を尋ね、2 人目のレビュー担当者がモデル変更のロールバック計画を求めました。どちらの回答も現在はリリースの記録の一部になっており、次のレビュー担当者はそこを確認します。

変更ポリシーの承認

リリースレビューはリリース全体を対象とします。マニフェストの changePolicy ブロックはさらに踏み込み、プラグインのデプロイ対象に対するどの種類の変更に承認が必要か、そして何人の承認が必要かを定めます。

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

3 つのクラスは、website(Web アプリ)、bff(バックエンド・フォー・フロントエンド)、migration(データベースマイグレーション)です。classes で指定した各クラスには、approvals にそれぞれ 1 から 10 までの人数を設定する必要があります。省略したクラスは管理対象外となり、スキーマはそれを記載漏れによってではなく、選択として明記することを求めます。私たちがマイグレーションに 2 件の承認を求めているのは、マイグレーションが元に戻しにくい唯一の変更だからです。

承認は異なる人の人数で数えられ、提案者は決してその中に含まれません。これを支えるルールは知っておく価値があります。それぞれに拒否の結果があるからです。

  • 変更を提案した本人による承認は、TRUST_APPROVAL_SELF_APPROVAL で拒否されます。
  • そのクラスの変更をそもそも行えない人による承認は、CHANGE_CLASS_NOT_PERMITTED で拒否されます。
  • 変更内のいずれかのコミットが組織のエージェント ID で署名されている場合、定足数は通常の最小数に 1 を加えたものとなり、エージェント自身の票は数えられません。
  • 各承認には、その承認者が確認した差分とヘッドが記録されます。最後の承認の後に変更が更新された場合、マージは HASH_MISMATCH で拒否され、新しい内容に対して承認を集め直す必要があります。

第 2.26 章「AI コーディングツールで構築する」で説明しているように AI(人工知能)コーディングツールを使って構築する場合、この 3 番目のルールが重要になります。エージェントが書いた作業には、人が書いた作業よりも 1 件多い人間の承認が必要です。それを見込んで計画してください。

署名と検証

すべてのイメージとパッケージは、それを構築したパイプラインによって署名されます。署名済みイメージであることは、ステージングへのゲートの 1 つです。dev スペースは最初から署名済みイメージのみを実行します。Enterprise では、管理者が各ネームスペースを、署名されていないイメージを記録する設定か拒否する設定のいずれかにし、ネームスペースを 1 つずつ拒否に移行します。こうして本番環境では、パイプラインが構築し署名したイメージだけが実行されるようになります。署名はビルドの一部であり、リリースの前に追加するものではありません。

これらすべてに通じるルールは、署名の検証失敗は警告ではなく、常に拒否であるということです。SIG_INVALID を受け取ったチェックは停止します。署名されていないバージョンにフォールバックすることも、ログに注記を残して処理を続けることもありません。ビルドログ内の警告は、それを読まなかった人全員にとって合格と同じだからです。

同じルールは、メディアで受け渡すすべてのものに適用されます。エアギャップ環境の顧客向けの封印済みバンドルは、何かを展開する前にお客様の公開鍵で検証されます。そのコマンドは 第 2.25 章「エディションごとに構築する」で示しています。

配信ID

プラグインは、それぞれ名前を持つ複数のものを通じて提供されます。リポジトリ、署名鍵、デプロイ先ネームスペース、レジストリのプレフィックス、データベーススキーマ、一連のドメイン、変更ポリシーです。そのいずれもが、2 つのプラグインが衝突したり、1 つのプラグインがずれたりし得る箇所です。デリバリー ID は、これらすべてを保持するプラグインごとの 1 つの署名済みレコードです。そのため、リリースパス上のすべてのチェックが同じ答えを参照し、不一致があれば拒否します。

お客様が提供する部分は、マニフェストを通じてのみ提供します。schema、db、domains、changePolicy、そしてリポジトリの URL です。残りはプラットフォームがレコードに補完し、署名します。ご自身のネームスペース、レジストリのプレフィックス、署名鍵を指定することはありません。これらは割り当てられるものであり、それらを宣言しようとするマニフェストは、チェックが疑わざるを得ない主張をしていることになります。

署名済みレコードには 11 個のフィールドがあります。プラグインのスラッグ、所有組織、構築を担う組織、リポジトリ、署名鍵の名前、デプロイ先ネームスペース、レジストリのプレフィックス、データベーススキーマ、ドメイン、変更ポリシー、そしてレジストリのプレフィックスが存在する前に使用していた旧イメージ名の短いリストです。この最後のリストは縮小することしかできません。署名されているため、新しい署名でエントリを削除することはできても、こっそりエントリを追加することはできません。署名は、これら 11 個のフィールドの標準的な正規化 JSON 形式に対する Ed25519 署名であるため、「Tomás」や「Sinéad」を含むレコードでも、どこでも同じように検証されます。

リリースがそのレコードと一致しない場合、最初の拒否が適用されます。

コード 発生条件 HTTP
DELIVERY_IDENTITY_MISSING プラグインのレコードが存在しない 403
DELIVERY_PATH_REFUSED レジストリのプレフィックス外へのイメージのプッシュで、署名済みの旧名リストにも記載されていない 403
NAMESPACE_MISMATCH 別のネームスペースを対象とするデプロイ 403
IMAGE_NAME_COLLISION 別のプラグインがすでに使用しているイメージ名 409
CHANGE_CLASS_NOT_PERMITTED ポリシーが管理対象としていない変更クラス 403

IMAGE_NAME_COLLISION は多くの人が驚くものです。別の名前を選び、決して再利用しないでください。イメージ名を共有すると、あるプラグインの昇格によって別のプラグインのポッドが動いてしまう可能性があります。

コミットおよびスコープ設定されたマイグレーション

マイグレーションはプラグインのイメージに含めて出荷され、新しいバージョンが起動する前に、SDK の唯一のマイグレーションランナーである nexus-migrate によって実行されます。独自の適用処理を書く必要はありません。いずれかのリリースが先に進む前に、同じランナーが使い捨てのデータベースに対してマイグレーションを 1 ファイルずつ適用します。そのため、失敗するマイグレーションはそこで失敗します。テンプレートのシャドウビルドは、ファイルごとに 1 回、順番にランナーを呼び出し、本番環境と同じように各ファイルを記録します。

ランナーのルールは、ゲートがチェックするルールをコードとして書いたものです。

  1. スキーマのマイグレーターロールとして接続し、すべてのファイルをスキーマの所有者として実行します。それ以外のログイン、とりわけスーパーユーザーは拒否されます。ファイル自身がロールを切り替えようとする場合は、何かが実行される前に拒否されます。
  2. 番号 0 のテナンシーファイルは、適用後に編集されることはありません。テナンシーの変更には専用のリビジョンファイル 000_tenancy_r<N>.sql を用意し、これは nexus-tenancy render --revision <N> が作成します。
  3. 通常、ランナーが各ファイルのトランザクションを管理し、ファイル内の BEGIN や COMMIT を拒否します。独自にトランザクションを管理するファイルは、ステートメント単位で実行されることを宣言します。その場合、そのファイルが開くすべての BEGIN には対応するものが必要です。
  4. ランナーは台帳を保持し、ファイルごとに 1 行、そのファイルの SHA-256 と実行方法を記録します。適用済みのファイルがその場で変更されることはなく、変更は番号を付けた新しいファイルとして行います。
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

スコープ付きとは、すべての新しいテーブルが organization_id、owner_user_id、business_unit_id を持ち、さらに gates/demo-exempt.json が理由を付けてそのテーブルを除外しない限り is_demo マーカー列を持つこと、主キーの先頭が組織であり外部キーがそれを引き継ぐこと、そして行レベルセキュリティが強制されていることを意味します。migrations-are-scoped ゲートはすべてのファイルについてこれらのルールをチェックし、migrations-commit-what-they-open は各ファイルが開いたものをコミットしているかを数えます。2 つ目のゲートが存在するのは、かつて暗黙にロールバックされたマイグレーションが終了コード 0 で終了し、作成されるはずだったテーブルが存在しなかったことがあるからです。

もう 1 つ、すべてのリリースに含まれるファイルがあります。scripts/ci/required-env は、サービスの起動に必要な環境変数を、設定ローダーから取得した JSON 配列として出力します。リリースパスはこれを実行し、デプロイでそのすべてが設定されていないリリースを拒否します。そのため、変数の不足は、起動しないポッドによってではなく、リリースの前に検出されます。

node scripts/ci/required-env

スキルのリリース

2 種類のスキルは異なる経路で利用者に届くため、それぞれ異なる方法でリリースしてください。

マニフェストスキルは、プラグインの skills[] 内の型付きの行であり、プラグインとともに出荷され、ほかの部分と同じ昇格を経ます。オンボーディングでは、リリースのたびにスキルセット全体がレジストリに同期されます。スキルをセットから外すとそのスキルは無効になります。Enterprise では、不正なスキルが 1 つでもあると同期は 1 つも反映されないため、新しいバージョンの半分ではなく、以前のバージョンが引き続き稼働します。

Skills Engine のスキルはライブラリから公開されます。Enterprise では、書き込みツールを追加するスキルは、指名された 2 名がパスキーで承認するまで待機し、提案者はその 2 名に含まれることができません。承認されたバージョンは、まずシャドウで実行され、次に指名されたゲートの下で 1 つのユニットに対するカナリアとして実行され、その後全員に対して実行されます。ゲートが満たされない場合は自ら停止します。お客様のプラグインと Skills Engine のスキルが互いに依存している場合は、先にスキルを公開して全員に行き渡らせてから、それを呼び出すプラグインのリリースをパイロットから出してください。

チャネルとインストール

リリースがパイロットを通過してすべてのユニットに到達すると、チャネル上で提供され、各ユニットが自らのチャネルを選択します。すべての移行には、そのユニットの管理者の同意が必要です。「Channels and installs」ページには、どのユニットがどのバージョンを実行しているかが表示され、エラー率は件数のみで示されます。お客様の拡張機能がどのように動作しているかはわかりますが、誰がそれを使って何をしたかがわかることは決してありません。

チャネルとインストール
チャネルとインストール
どのユニットが carrier-sync のどのバージョンを実行しているかを示す画面で、1 つのユニットに対するロールバックが開かれています。モーダルに、何が変わるか、何が維持されるか、そして 2 人目の担当者、つまりそのユニット自身の管理者が必要であることが記載されている点に注目してください。

当社の carrier-sync プラグインは 3 つのバージョンを同時に実行していますが、これは通常の状態です。ほとんどのユニットは現行リリースを使用しており、1 つのユニットは明示された日付まで維持されるチャネル上で古いバージョンにとどまり、リリース候補はまだ誰も選択していないチャネル上にあります。これに抗わないでください。監査のために安定性を必要とするユニットには、それを得る権利があります。

拡張機能のログとメトリクス

お客様のパックのログとメトリクスのページは、閲覧が許可されているユニットにおける、お客様自身のワークロードに固定されています。ユニットと環境で絞り込むことができ、件数、所要時間、状態を確認できます。

お客様のパックのログとメトリクス
お客様のパックのログとメトリクス
Cold chain 自身のログとメトリクスを、Rotterdam のパイロットに絞り込んだものです。ログ行を見てください。逸脱を報告した人物は隠されており、クレームメモの本文はまったく記録されていません。

個人に関するフィールドは行が書き込まれる前に置き換えられ、クレームの本文、メール、ドキュメントの内容などの顧客コンテンツがログに書き込まれることは決してありません。ログは 14 日間保持されます。組織はゲートウェイによって設定され、お客様のクエリによって設定されることは決してないため、別の組織を指定するクエリは TENANT_BOUNDARY で拒否されます。ドック内のアシスタントは、お客様と一緒に同じログを読むことができ、読めるのはこれらのログのみです。ある朝、逸脱記録が遅れて届いた理由を尋ねたところ、アシスタントは 18 分間の再試行を、ある岸壁の電源供給からの重複した読み取り値にまで突き止めました。

ロールバック

ロールバックには 2 種類あり、どちらもスイッチではなく、レビューを受ける変更です。

環境のロールバックでは、直前のバージョンを使用します。各環境はそれを 30 日間保持します。ロールバックはリリースに対する変更として準備され、実行内容をプレビューし、2 人目の担当者を必要とします。承認されると、パイプラインは約 1 分でロールバックします。すべてのロールバックは時間が計測され、すべての訓練も同様です。そのため、必要になる前に一度練習しておいてください。1 つのユニットのロールバックには、「Channels and installs」ページを使用します。ロールバックのモーダルには、何が変わるか(そのユニットが古いバージョンを再び実行し、そのエラー率が 1 時間監視されること)、何が維持されるか(他のユニット、およびそのユニットの設定と記録)、理由、そして 2 人目の担当者が誰であるか(そのユニットの管理者)が記載されています。

設定と記録はロールバック後も保持されるため、各リリースは、直前のバージョンが新しいバージョンの書き込んだデータ上で再び実行される可能性があるという前提で計画してください。これが、ロールバックする可能性のあるリリース内ではマイグレーションを追加的なものに保つべき実際的な理由であり、各マイグレーションに 2 名の承認を求める理由でもあります。モデルの変更も同様です。レビュー担当者は、グラフ変更リクエストを承認する前に、そのロールバック計画を求めることができ、また求めるべきです。

スキルのロールバックはより穏やかです。live ラベルを以前のバージョンに戻すのは 1 つの手順で済み、すでに実行中のものは、開始時のバージョンで完了します。

バージョンの廃止

リリースは、一度作成されたら決して編集されません。もう使用すべきでないバージョンは取り下げられ、修正は新しいバージョン番号として出荷されます。SDK 自身のリリースチャネルも同じ慣習に従っています。問題のある SDK バージョンは取り消され、同じ番号のまま別の内容に置き換えられることは決してありません。これに倣ってください。2 つの異なるビルドを意味しうるバージョン番号は、それに関するあらゆる証拠を無価値にしてしまうからです。

プラグインやパックを取り下げると、新規インストールが停止します。ユニットは移行するまで実行中のバージョンを維持するため、取り下げはオフスイッチではなく、合図であり期限です。ユニットの管理者に、どのバージョンへいつまでに移行すべきかを伝えてください。

スキルの廃止も同じ考え方に従いますが、手順が 1 つ増えます。Skills Engine は、代替スキルのケースを実行した後、残っているすべての呼び出し元を代替スキルに移行し、新しい実行を停止し、バージョン、ケース、封印された実行記録を保持します。そのため、代替スキルに問題があると判明した場合には、スキルを元に戻すことができます。

リリースチェックリスト

これは、Cold chain の各リリースの前に当社が確認するリストです。プラットフォームがその大部分を代わりにチェックしてくれるため、短いリストになっています。

  1. バージョンが一致していること:マニフェスト、pack.json、および変更された場合はナレッジモデル。
  2. すべてのゲートが、クリーンな状態からローカルでグリーンであり、すべての新しいテストが最初に失敗することが確認されていること。
  3. 「Manifest and permissions」ページに権限の拡大が表示されていないこと、または拡大が意図どおりであり、レビュー担当者がその理由を把握していること。
  4. すべてのマイグレーションが、新しい番号付きファイルであり、スコープが限定され、使い捨てのデータベースに対して問題なく適用されること。
  5. scripts/ci/required-env にサービスが必要とするすべての変数が記載され、デプロイメントがそれぞれを設定していること。
  6. モデルの変更も含め、ロールバック計画が変更内に記載されていること。
  7. 作成者ではないレビュー担当者 2 名が今週対応可能であること。

最後の項目は些細なことに聞こえます。しかし、すべてのゲートを合わせたよりも多く、当社のリリースを遅らせてきたのはこの項目です。