設計方針の要約

推奨：Go製のローカルCLIを核に、公開仕様から生成するカタログと、共通グラフモデルで入出力を分離する。 公開Webサイトはこの設計書と架空データの閲覧専用とする。実環境のAPIキー、state、構成図を公開ホスティングへ送信しない。

利用場面は社内の現状把握と顧客提案・報告。APIによる観測、stateの保存状態、planの予定、HCLの宣言、YAMLの提案を区別し、同じ事実として混在させない。単一入力を既定とし、複数入力の統合は明示的なID対応表がある場合に限定する。

2026年10月15日の公式確認では、Terraform v2は2026年12月末に保守終了予定、v3とは非互換。両方を別アダプターとして扱う。旧iaas-api-goは統合SDKへ移転しており、新規コードは統合先を使用する。sacloud-mcpは提供終了のため依存しない。AppRun共用型の権限例外により、読み取り専用保証が取れないAPI Collectorは有効化しない。

本成果物は設計案であり、実環境収集・定期更新・公式アイコン同梱は未実装。添付サンプルは架空データ／スキーマ案であり、実行済みカタログと混同しない。

アーキテクチャとコンポーネント

flowchart LR
  subgraph local[ローカル または 自社環境]
    A[API 読取専用] --> C[Collector]
    B[usacloud JSON] --> C
    T[Terraform state / plan / HCL] --> C
    Y[簡易 YAML] --> C
    C --> N[正規化・参照解決]
    N --> G[Graph JSON / JSON Schema]
    G --> V[契約検証・診断]
    V --> P[出力用コピー・マスキング]
    P --> R[Renderer 共通インターフェース]
    R --> D[draw.io XML]
    R --> M[Mermaid]
    R --> S[SVG / PNG]
    K[承認済みカタログ] -.-> C
    K -.-> N
    K -.-> R
  end
  subgraph public[公開情報のみの更新系]
    U[sources.yaml] --> F[取得・ハッシュ]
    F --> X[抽出・カタログ候補]
    X --> Q[差分・回帰テスト・PR]
    Q --> H[人によるレビュー]
  end
  H --> K

CollectorはCollect(context, request) -> snapshot + coverage + diagnostics、Normalizerはsnapshot + catalog -> graph、RendererはRender(graph, presentation, resolvedCatalog) -> artifacts + diagnosticsを想定。Go interfaceは薄く保ち、プラグインはまず同一バイナリ内登録。外部プロセス追加時は版付きJSON入出力とtimeoutを用いる。

API収集：最初にゾーン一覧を取得し、その後各サービスのscope規則で列挙する。グローバルなサービスをゾーンごとに重複収集しない。IaaSのページングはTotal・取得件数・重複IDを照合。開始／終了時刻を記録し、原子的snapshotとは呼ばない。初期並列度4、各ホスト2 req/s・burst 2・timeout 30秒・429/5xx最大3回jitter再試行を仮設定とし、公式制限と実測に合わせ調整する。401/403は無限再試行しない。GETだけでなくサービスごとの許可operationを固定し、削除・更新APIをSDKラッパーに露出させない。

usacloud：usacloud server ls --output-type jsonが公式記載の例。各コマンド・ゾーン・CLI版のenvelopeを別メタデータで受け取る。自動実行する場合は引数配列とコマンドallowlistを使いshell文字列を連結しない。公式JSON出力手順

Terraform：state/保存planはユーザーが信頼した環境でterraform show -jsonに変換したJSONを優先。stateとplanのvalues、resource_changes、after_unknown、sensitive mask、configuration.referencesを区別する。module/for_each/countのインスタンスaddressを保持し、delete/createを別状態にする。HCLはGoのHCL/ctyで静的解析し、moduleソース取得・data source実行・plan実行は自動では行わない。未解決式は文字列で保存せず安全なunknown表現にする。JSON形式

関係・グループ：NIC→switch、server→diskは実ID参照、LB→backendは明示backend定義から抽出。depends_onはdependencyエッジであり通信線にはしない。VPCルータ配下という境界はルーティング／接続が確認できる場合だけ確定。groupの親は表示上の単一親、membersは複数所属可。switchはノードとして接続を残し、groupにも表示できる。ブリッジ等のゾーンを跨ぐ線はLCAグループ上へ引き上げる。GSLB/オブジェクトストレージ/AppRunをIaaSのL2ネットワークへ勝手に所属させない。

描画：Goでlayout-neutral Graphを保持し、共通のLayoutPlanはRenderer側の別構造とする。draw.ioはローカル生成のmxGraph XML、SVGはベクター直描き、PNGはローカルの固定版ラスタライザーを使用。Mermaidはテキスト出力／ローカル固定版CLIで変換し、オンラインレンダリングAPIを使わない。全出力にlegend・警告・版・日時を含める。フォント・layout seed・ソート・小数丸めを固定し再現性を確保する。draw.io XML・Mermaid

既存事例からの判断：Terraform graphは依存順序の可視化であり、通信構成の意味は補う必要がある。Diagramsのコードとローカル描画の分離、cdk-diaの構造化IaCからの可視化を参考にする。ただし実行モデル・プロバイダ・アイコンが異なり、直接流用せず、関係解釈・入力形式追随・大規模レイアウトが主な失敗要因と見積もる。障害発生実績を確認したという意味ではない。

正規化グラフモデルのJSON Schema案

完全な機械可読案はgraph.schema.json、適合する架空例はgraph.example.json。型名・関係名をenumで閉じないことが、未知種別への耐性を作る。構造の不正と未知のリソース種別は別物として扱う。

{
  "schemaVersion": "1.0.0",
  "graphId": "example-vpc",
  "metadata": {"catalogVersion": "design-example.1", "inputKind": "yaml",
    "completeness": "proposal", "redactionProfile": "customer"},
  "nodes": [{"id": "server", "type": "sakura.iaas.server"}],
  "edges": [{"id": "e1", "source": "server", "target": "switch",
    "relation": "connected_to", "plane": "network", "evidence": "explicit"}],
  "groups": [{"id": "zone:demo", "kind": "zone", "members": ["server","switch"]}],
  "diagnostics": []
}

上記は読みやすさのための抜粋で、必須フィールドを省略している。検証・実装には完全版ファイルを使う。

Schemaでは参照整合性を保証できないため、意味検証で①node/edge/groupそれぞれID一意性、②edge端点存在、③group member/parent存在、④group親循環禁止、⑤scope整合、⑥secret値不在、⑦収集開始≦終了、⑧顧客プロファイル許可属性だけ、を検証する。networkは循環可能なので全GraphをDAGに制限しない。

未知のresource typeはgeneric.resourceで描画し、ノードに「未対応リソース」、図フッターに件数、診断JSONとstderrにUNKNOWN_RESOURCE_TYPEを出す。既知のendpointを持つ関係は保持する。欠損端点は捏造せず、参照だけのplaceholderノード（lifecycle=unknown）を診断付きで作る。未知のJSON構造を勝手に修復する処理とは区別する。

sources.yamlとカタログのスキーマ案

添付：sources.yaml・sources.schema.json・catalog.schema.json・catalog.example.json・proposal.example.yaml。sources.yamlは今回実際にHTTP取得した日時・本文SHA-256・結果を含む。認証付きAPIとTerraform schemaコマンドは未実行で、備考に区別している。nullは未確認を意味し、偽のハッシュで埋めない。

リソース一覧は手書きしない。だが「この属性がswitchへの接続」「このアイコンはこのサービス専用」といった意味はスキーマだけで完全には推定できない。自動候補生成と人のレビューを分け、未レビュー種別もgenericで残す。OpenAPIの全schemaをリソース化するとrequest/response DTOまで混入するため、operationと安定ID・List/Getペアで候補を絞る。SDKの公開型も同様に候補であり確定実体ではない。

Terraform schema抽出は空の専用ディレクトリで固定版providerだけを初期化し、backendを無効化する。terraform providers schema -jsonのformat_version、provider実バージョン、resource schema version、lockfile digestを別保存する。ユーザーのstate・認証情報は渡さない。providerは実行バイナリなのでネットワーク・ファイルアクセスを制限した一時コンテナで実行し、署名／checksumを検証する。公式schemaコマンド

URL管理：全取得先はsources.yaml／紐付くendpoint manifestに置く。SDKの既定endpointも設定注入対象とし、RendererにAPI URLを持たせない。実在確認済みマニュアルURLと、未実行のAPI operationは別の証拠として管理する。リリース監視には今回実取得したGitHub releases APIを用いる。SDK型抽出、Terraform schemaコマンド、認証付きAPIは別レコードで未検証／無効とし、HTMLのhashを機械可読schemaのhashとして使わない。

ゾーン・プラン：facility/product仕様のList操作を使って動的更新する。取得できない場合は承認済みsnapshotを使い古さを示す。ゾーンやプランを削除検出しても即消去しない。履歴図や旧stateを描けるようtombstoneを残す。料金は公開価格・契約別価格・税区分・通貨・取得時刻・有効日を別管理し、図生成に必須としない。API仕様上は価格取得手段があるが、個別サービスの網羅と契約価格は実機確認が必要。施設・プラン・料金

優先順位・競合：API/OpenAPIの属性仕様、固定版provider schemaのIaC名、SDKの取扱実体を用途ごとに使い分ける。機械可読な一次情報を優先するが、ニュースの正式廃止通知はスキーマに残った型の状態を上書きできる。食い違いはconflictとしてPRに出し自動決着しない。日付や名称だけの一致で型を統合しない。

対象種別の対応方針：サーバー／ディスク／スイッチ／ブリッジ／VPCルータ／LB／GSLB／DB・NFSアプライアンスはIaaS系候補。エンハンスドLB、オブジェクトストレージ、AppRunは別API・scope・認証の確認単位とする。種別がcatalogにあること、Collectorで列挙可能なこと、関係を意味付きで描けること、適切なアイコンがあることを別capabilityで表示する。

アイコン：一般のさくらアイコン公開記事はCC BY 4.0を案内する。ZIP同梱の利用条件原文・版・digest・帰属文言を導入前に保存する。一方クラウドサービスアイコンは改変やアイコン自体の再配布を禁じる独自条件。公開Web配信／draw.io埋込が許容されるか未確認のため、今回のデモは独自の汎用図形を使う。将来の正式出力は利用許諾確認後に公式資産をローカル配置し、assetId→サービス→licenseIdの対応を固定する。該当資産がない／許諾不明の場合は汎用図形とする。Mermaidのテキスト出力は原則ラベル主体で、公式画像の完全再現を保証しない。

更新パイプラインの詳細

トリガー：日次02:00 JST（cron 0 17 * * * UTC）でリリース・ニュースRSS・OpenAPI・公開ページの変更検知。週次月曜03:00 JST（日曜0 18 * * 0 UTC）に固定版schemaから全面再生成。手動workflow_dispatchでsource ID指定、providerアップグレードPRでも差分テスト。GitHub cronは遅延・省略があり得るので最終成功時刻を別監視し48時間失敗で通知する。

1. sources.yamlを契約検証。https/許可ドメイン・redirect先・最大10MB・timeout・robots/利用規約を検査する。ローカルファイルやプライベートIP宛取得を禁止する。
2. ETag／Last-Modifiedによる条件付き取得。304は検証成功時刻だけ更新。生本文のraw hashで変化検知し、HTML本文抽出後のsemantic hashと分ける。ハッシュは改ざん防止署名の代替ではない。
3. raw snapshotを公開情報用の隔離領域へ保存し、extractor版とURL、取得時刻、content-typeを記録。本文抽出が失敗したら旧本文で更新成功扱いにせずsourceをfailedとする。
4. 固定版provider v2/v3、現行SDK／OpenAPIを独立抽出。未知型をinventoryへ追加し、overlay未対応ならgeneric候補とする。アーカイブ／repository移転／リリース停止も検知する。
5. 型追加、属性追加・型変更・必須化・sensitive変更、廃止候補、名称変更候補、zone/plan変更、icon/license変更を分類。正式廃止の根拠がない欠落は「廃止候補」。renameは旧名→新名の明示aliasと根拠を人が確定する。
6. draft catalogを生成し、契約・意味検証・四構成golden・旧カタログ比較・全Renderer・秘密漏えい検査を実行。仕様消失や失敗したsourceに由来する大量削除は自動適用せず停止する。
7. source IDごとに同一更新ブランチとPRをupsertし、重複PRを防止。PRが失敗しても採用済みcatalogは維持。破壊的変更はdraft PRと専用ラベル、通知はGitHub PR通知を既定とする。
8. 人がレビューしてmerge。branch protection／CODEOWNERSでcatalog＋security担当承認を必須化し、botのbypass・自動mergeを禁止する。merge後、署名付きartifactとdigestを発行し前版を保持する。

CI境界：公開仕様の監視はGitHub-hosted runnerでもよいが、実環境snapshotの回帰はネットワーク制御付き自社runner内で実行する。公開PRには架空goldenだけ載せる。fork PRにsecretsを渡さない、pull_request_targetで未信頼コードを実行しない、ActionsはSHA固定。read jobはcontents:read、専用PR作成jobだけcontents/pull-requests:write。実環境のAPIキーは公開更新jobに持ち込まない。

鮮度SLO（提案）：公開変更の検知24時間以内、通常型追加の候補PRは7日以内、破壊的変更は検知当日に担当確認。マージ期限は人の業務SLAとして設定する。30日警告はcatalogの生成日ではなく、必須sourceの最古の成功検証時刻を基準にする。再生成だけで鮮度を更新しない。最新確認と実変更・公開版日付を分離し、source失敗をバンドル全体の「fresh」で隠さない。

catalogのrequiredSourceIdsとsourceHealthに必須集合・各sourceの最終成功・現在結果を保存する。GraphにはcatalogFreshnessとして評価日時・状態・閾値・最古成功時刻・失敗数・manifest digestを固定し、後日も判定を再現できるようにする。必須source未確認はunverified、現在失敗はsource-failed、期限超はstale。全source成功で期限内の時だけfresh。lastVerifiedAtとGraphのcatalogVerifiedAtは互換用の集約時刻で、freshness判定の代替にはしない。正式catalogは必須source IDの存在・重複・欠落も意味検証する。

図フッター例：Catalog 2026.10.1 / 仕様確認 2026-10-15 / 環境取得 2026-10-15 10:00–10:02 JST / 部分取得 1 service / 未対応 2。proposalでは「環境取得」ではなく「提案入力日」。経過30日超または必須source取得失敗時は警告。顧客提出では説明責任を残し、社内source pathなどは除く。

PRテンプレート案：

件名: catalog: [追加/属性変更/廃止候補/名称変更候補] 対象sourceと版

## 変更内容
- 追加型 / 変更属性 / deprecated / aliases / zone・plan
- 旧→新、破壊性、影響Collector・Renderer・関係ルール

## 根拠
- source ID / 実URL / 取得日時 / upstream版・commit / SHA-256
- 廃止・名称変更の公式告知 / 競合・未確認事項

## 検証
- Schema / 参照整合 / 旧Graph互換 / 四構成golden
- draw.io / Mermaid / SVG・PNG / mask・secret検査
- 差分図添付（架空データのみ）/ failed・skipの理由

## 人の判断
- 型の同一性・関係意味 / 公式アイコン組合せ / ライセンス
- 移行手順・rollback / 採用判断と担当者
- 自動マージ禁止。承認後のみ配布版へ反映

回復：採用catalogはsemver＋content digestで固定。CI失敗時は前版のまま図生成可能。誤更新時はmanifestの版を前版へ戻して同じ入力で再生成し比較する。互換overlayを削除せずdeprecated化する。公開仕様snapshotは原則90日、署名済み採用artifactは履歴保持とする（規約に応じ調整）。

主要な設計判断の記録（ADR）

GoとPythonの比較：Goは型付け・HCL/cty・SDK利用・配布で優位、PythonはJSON/HTML解析や試作が速い。今回は継続運用が最重要なのでGoを推奨する。Go版の最低バージョンは現行SDKのgo.modと採用releaseを実装時に検証し、ここで固定しない。PNGの日本語フォントとローカル変換器は別途bundle管理する。

リスクと対策・テスト方針

秘密・マスキング：API token/secretは環境変数または自社secret storeから注入し、引数・ログ・stacktrace・HTTPヘッダー出力に残さない。state/planには秘密が含まれ得るので一時領域を権限制限し既定はメモリ処理、保存snapshotは暗号化・保存期間7日を提案。アップデート系へ環境情報を渡さない。外部LLMも使わない。

顧客向け簡易版は役割名・サービス・ゾーン境界・接続だけ、詳細版は許可されたプラン・CPU/RAM・容量などを追加。IP/host名/name/tag/description/nativeId/provenanceやSVG metadata・draw.io XML hidden fieldsまで再帰的に除去／匿名化する。プラン・容量も顧客契約によって非公開にできる。マスキングはRenderer前の不変コピーで行い、全出力とPNG埋込メタデータを最後に検査する。単なる見た目の塗りつぶしは禁止。

テスト計画：

画像goldenはフォント・レンダラー版・seed・viewportを固定、座標小差分と意味差分を分ける。更新PRでgoldenを自動承認しない。MVPの受入条件は4構成×4出力の意味一致、unknownを保持、部分失敗を可視化、漏えいfixtureゼロ。

性能目標（未測定の受入基準）：8-core/16GBの評価機で500 nodes／1,000 edgesの正規化＋簡易SVG描画p95 3秒以内、PNG 5秒以内を仮目標とする。API取得時間は別計測。5,000 nodesはscope別に分割、全体は集約図。性能試験後に目標を確定する。公開設計サイトは静的HTML/CSS/小さなJS・システムフォント・外部CDN無しとし、初期転送量250KB以下（圧縮前のHTML/CSS/JS合計）を目標とする。

段階的な実装計画（MVP → 拡張）

1名の経験ある開発者＋インフラレビュー担当を仮定した概算は、0が2–3日、1が2–3週、2が1–2週、3が2–3週。4・5はサービス数・権限・組織要件を確認後に見積もる。実績値や納期の確約ではない。MVPは対象サービスを宣言し、全サービス対応を名乗らない。

今回の公開物は設計書サイト、機械可読schema、実URL確認台帳、架空入力、架空デモのSVG/draw.io/Mermaid出力まで。実環境API呼出し・Terraform実行・本番更新Actionsは行わない。小さなデモを製品実装と誤認しないよう画面に常時表示する。

不明点・要確認事項

不明点を確定情報に置き換えず、未確認sourceはdisabled、未確認capabilityはneeds-verification、未レビュー型はgenericという形で設計に組み込む。