Hane Platform

定義をコードで管理する

型・Workflow・承認の規則・Agent などの定義を YAML のマニフェストで書き、検証・apply・ReleaseBundle・有効化の順に反映する仕組みを説明します。

このページでは、Hane の定義をマニフェストで書いて Git で管理し、検証してから有効にするまでの流れを説明します。コマンドの詳しい使い方は hanectl、書き方の例はマニフェストを書くを参照してください。

なぜコードで管理するのか

業務の型、Workflow、承認の規則、Agent の定義は、業務の結果を大きく左右します。Hane ではこれらを Kubernetes のマニフェストと同じ形の YAML で書き、Git で管理します。

変更は Git の差分として残り、プルリクエストで審査できます。
どの時点で何が効いていたかを再現でき、前の状態に戻せます。
コンソールでは定義を変えません。画面での変更と Git の中身がずれることはありません。

マニフェストの形

どのマニフェストも apiVersion・kind・metadata・spec の 4 つを持ちます。

apiVersion: workflows/v1alpha1
kind: Schedule
metadata:
  name: daily-expiry-scan          # 英小文字・数字・ハイフン。プロジェクトと kind の中で一意
  annotations:
    description: 毎朝、申入れの期限が近い契約に満了対応の案件を作る
spec:
  every: day
  at: "07:00"
  timezone: Asia/Tokyo
  forEach:
    type: LeaseContract
    where: record.status == "active"
  workflow: lease-expiry

1 つのファイルに --- で複数のマニフェストを並べられます。ディレクトリを渡すと、その下の *.yaml をすべて読みます。
知らない項目は拒否します。綴りの誤りが気づかないうちに無視されることはありません。
status と定義のバージョンの番号はサーバーが書きます。ファイルに書くと拒否します。
マニフェスト同士は名前で参照します（workflow: lease-expiry）。どのバージョンを使うかは ReleaseBundle が決めます。
秘密値と、環境ごとに違う値はファイルに書きません。環境ごとの EnvironmentBinding で名前を解きます。

種類

apiVersion の / の前が、その kind を持つサービスです。

定義（ReleaseBundle に束ねて、有効化で効く）

apiVersion	kind
`data/v1alpha1`	`Schema`・`Ontology`・`Rule`・`Calculation`・`Migration`・`Axiom`・`Aspect`
`workflows/v1alpha1`	`Workflow`・`Schedule`
`approvals/v1alpha1`	`AssignmentRule`・`DeciderPolicy`
`agents/v1alpha1`	`Agent`・`EvalSuite`・`TriageRule`
`documents/v1alpha1`	`DocumentType`・`ExtractionSchema`
`communication/v1alpha1`	`ContactPolicy`・`CallBriefTemplate`
`gateway/v1alpha1`	`Route`・`PublishedApi`・`ToolExposure`
`integrations/v1alpha1`	`Connection`
`browser/v1alpha1`	`BrowserFlow`
`platform/v1alpha1`	`Budget`
`factory/v1alpha1`	`Application`

設定（束ねずに、apply するとすぐ効く）

apiVersion	kind
`release/v1alpha1`	`EnvironmentBinding`・`SourcePolicy`
`platform/v1alpha1`	`RoleBinding`・`GitSource`
`documents/v1alpha1`	`DocumentSource`
`communication/v1alpha1`	`SenderIdentity`・`ContactRetention`
`gateway/v1alpha1`	`Consumer`

設定は、変えたらすぐ効くべきもの（権限、環境ごとの接続先、保持の日数など）です。apply ごとにリビジョンが残り、hanectl rollout undo <kind> <name> で 1 つ前に戻せます。

反映の流れ

検証する。 hanectl validate -f <ディレクトリ> が、サーバーにつながずに形と参照（存在しない Agent や AssignmentRule、Schema のない型など）を確かめます。サーバーと同じ検証の部品を使います。
差分を見る。 hanectl diff が、いまの draft との差分を出します。破壊的な変更や権限が広がる変更には印が付きます。
apply する。 hanectl apply で draft を保存します。定義を apply できるのは dev の環境だけです。この時点ではまだ効きません。
ReleaseBundle を作る。 hanectl release create -f bundle.yaml で、Bundle に挙げた範囲の draft を 1 つの ReleaseBundle に束ねます。中身が同じなら同じ ID になり、作り直しません。
有効化する。 hanectl release activate <id>（または release create --activate）で、その環境の有効なバージョンを切り替えます。
昇格させる。 hanectl release promote <id> --to <組織>/<プロジェクト>/stage で、同じ中身の ReleaseBundle を stage・prod へ運び、そこで有効にします。

Bundle は束ねる範囲を書くファイルで、サーバーには送りません。

apiVersion: release/v1alpha1
kind: Bundle
metadata:
  name: vehicle-lease
spec:
  resources: [schemas/, ontology/, rules/, workflows/, schedules/, policies/, agents/]

有効化で確かめること

有効化は、すべての確認が通ってから一度に切り替えます。どれかが通らなければ切り替えず、前の ReleaseBundle のまま動きます。失敗した理由は GET /v1/definitions/active の pending に残ります。

確認	内容
名前の解決	ReleaseBundle が参照する `binding:` の名前が、その環境の EnvironmentBinding ですべて解けること
データの移行	項目の名前や型を変える Migration を当てられること。大きな移行は、有効化の前に `hanectl migrate backfill` で進めておける
評価	stage・prod では、そのバージョンの EvalSuite がすべて通っていること
審査	stage・prod で Agent に新しい外への操作のツールを持たせるもの、AI に承認を任せる範囲を広げるものは、作った人と別の人が `hanectl release review` で通していること
人の操作	prod の切り替えは人が自分のログインで行う。CI の API キーで有効にしようとしたものは `pending` に残り、人を待つ

有効化のあとも、進行中の案件は始めたときの ReleaseBundle で動き続けます。新しく始まる案件から新しい ReleaseBundle を使います。

戻す・試す

戻す。 hanectl rollout undo で、前の有効なバージョンに戻します。戻せない Migration を戻すことになる場合は止まり、手順を返します。
カナリア。 hanectl release canary <id> --percent 10 で、有効なバージョンはそのままに、新しい案件の一部だけで別の ReleaseBundle を試せます。release canary promote で有効にし、release canary abort でやめます。
履歴。 hanectl rollout history で有効化の履歴を、hanectl get --at <時刻> でその時点の有効なバージョンと設定を確かめられます。

Git からの反映

反映の方法は 2 つあります。

方法	内容
push 型	CI などから `hanectl apply` と `release create` を実行して送る。`apply` はリポジトリ・コミット・パスを出どころとして記録する
pull 型	`GitSource` を apply すると、Hane が決めた間隔で Git の ref を読み、検証・apply・ReleaseBundle の作成・有効化まで行う。登録したプロジェクトでは、手元からの `apply` は拒否され、Git だけが入力になる

次に読む

マニフェストを書く型・Workflow・Agent の書き方の例

hanectlコマンドの一覧と使い方

業務データSchema と Ontology で決めた型のレコード

デプロイdev から prod へ昇格させる