CML遠隔構築支援システム 要件定義

対象: Codexから 192.168.x.x 上の Cisco Modeling Labs 2.x を遠隔操作する初期完成版

再定義日: 2026-06-23 / 実装済み内容に合わせて再整理

1. 目的

本システムは、ユーザーから受けたネットワーク構築依頼を、フォルダ単位の設定ファイルと操作ログに変換し、Cisco Modeling Labs上へ再現可能な形で構築することを目的とする。 Codexは設定ファイルを作成・更新し、その内容に基づいて小さな単機能ツールを順番に実行する。 実行後はCML上の状態、ノード状態、L3アドレス、コンソールコマンド結果、疎通確認結果を成果物として保存する。

可視化
構築依頼、CMLラボ情報、設定、結果、ログをフォルダ内に残し、何を実行したかを追跡できる。
再現性
1つの依頼フォルダと1つのCMLラボを対応させ、同じ構築を再実行しやすくする。
検証
APIによる状態確認とコンソールCLIによる実機相当の確認を組み合わせる。

2. 初期完成版の範囲

分類 対応内容 初期版での実装状況
CML接続 CML Controllerへ認証し、APIでラボやリソースを操作する。 check_cml_connection.py、共通処理 cml_common.py で対応済み。
認証情報 通常実行時はユーザー名とパスワードを都度入力する。Codexからの自動実行時のみ --use-env を利用できる。 環境変数への恒久依存は避け、各ツールが入力プロンプトを持つ。
依頼フォルダ 構築依頼をフォルダ単位で管理し、1フォルダを1つのCMLラボに対応させる。 create_request_folder.py、validate_request_folder.py で対応済み。
ラボ操作 新規ラボ作成、既存ラボ紐付け、起動、停止、削除、状態取得を行う。 create_lab.py、link_existing_lab.py、start_lab.py、stop_lab.py、delete_lab.py、get_lab_status.py で対応済み。
トポロジ操作 ノード追加、インターフェース追加、リンク追加、ノード削除、ノード詳細取得を行う。 add_node.py、add_interface.py、add_link.py、delete_node.py、get_node.py で対応済み。
設定投入 ノードごとの初期コンフィグをCMLへ設定する。 set_node_config.py と configs/*.cfg で対応済み。
状態取得 トポロジ、要素状態、イベント、L3アドレスを取得する。 get_lab_topology.py、get_lab_element_state.py、get_lab_events.py、get_l3_addresses.py で対応済み。
CLI検証 CMLのSSHコンソールサーバー経由でノードへ接続し、show、ping、traceroute等を実行する。 run_console_command.py で対応済み。特権モード用に --enable を追加済み。
レポート 結果ファイルと検証サマリーを保存する。 サンプル用 write_verification_report.py と、依頼別の results/verification_summary.md で対応済み。

3. フォルダ構成

構築依頼は requests/ 配下のフォルダとして管理する。 フォルダ名は YYYYMMDD_依頼名 を基本とし、1つのフォルダには1つのCMLラボだけを紐付ける。

パス 役割
request.md ユーザーからの構築依頼、設計方針、IP設計、検証観点を記録する。
metadata.yaml 依頼名、対象CMLホスト、CMLラボID、ラボタイトル、作業日時などの管理情報を保持する。
cml-lab.yaml ラボ作成や操作の中心となる設定ファイル。対象ラボ、ノード、リンク、処理順序を記録する。
configs/ 各ノードに投入するコンフィグを保存する。例: P1.cfg、C1.cfg。
results/ CML APIの取得結果、コンソール実行結果、検証サマリーをJSONまたはMarkdownで保存する。
logs/ ツール実行ログをJSON Lines形式で保存する。
backups/ 将来の変更前バックアップ保存先。初期版では用途を定義し、必要時に利用する。
既存ラボを扱う場合も、新しい依頼フォルダを作成し、その metadata.yaml に既存ラボIDを紐付ける。 これにより、操作対象とログの置き場所を常に明確にする。

4. ツール設計方針

ツールは大きな一体型アプリではなく、単体で実行しても意味のある小さなコマンドとして構成する。 共通処理は cml_common.py に寄せるが、各ツールの責務は明確に分ける。

方針 内容
単機能 例: ラボを作る、ノードを追加する、リンクを追加する、状態を取る、コンソールコマンドを1つ実行する。
単体実行可能 各ツールはオーケストレーションなしでも実行でき、結果を results/ と logs/ に残す。
標準優先 HTTP API、SSH、Python標準ライブラリ、Paramikoなど標準的な仕組みを優先する。
不足分だけ独自実装 CML APIの呼び出し、フォルダ管理、結果保存、コンソールサーバー操作など、必要最小限を独自ツール化する。
操作の可視化 どのツールを、どの対象に、どの順序で実行したかをフォルダ内の成果物から追えるようにする。

5. 実装済みツール一覧

分類 ツール 用途
共通 cml_common.py 認証、CML API呼び出し、JSON保存、ログ追記、資格情報入力を共通化する。
依頼管理 create_request_folder.py
validate_request_folder.py		 依頼フォルダの作成と構造チェックを行う。
接続確認 check_cml_connection.py
get_cml_resources.py
list_node_definitions.py		 CML接続、リソース、利用可能なノード定義を確認する。
ラボ list_cml_labs.py
create_lab.py
link_existing_lab.py
start_lab.py
stop_lab.py
delete_lab.py		 ラボ一覧、新規作成、既存紐付け、起動、停止、削除を行う。
トポロジ add_node.py
delete_node.py
add_interface.py
add_link.py		 ノード、インターフェース、リンクを操作する。
状態取得 get_node.py
get_lab_status.py
get_lab_topology.py
get_lab_element_state.py
get_lab_events.py
get_l3_addresses.py		 ラボ、ノード、トポロジ、イベント、L3アドレスを取得する。
設定・検証 set_node_config.py
run_console_command.py
get_pyats_testbed.py
write_verification_report.py		 設定投入、CLIコマンド実行、testbed生成、検証レポート出力を行う。
オーケストレーション run_workflow.py cml-lab.yaml の安全な処理だけを順序実行する。初期版では限定的な自動実行に留める。

6. 標準ワークフロー

  1. ユーザーが自然言語で構築依頼を出す。
  2. Codexが依頼フォルダを作成し、request.md に要件と設計方針を整理する。
  3. cml-lab.yaml と metadata.yaml に対象ラボ情報を記録する。
  4. configs/ にノードごとのコンフィグを作成する。
  5. CMLへラボ、ノード、インターフェース、リンク、コンフィグを反映する。
  6. ラボを起動し、ノードがBootedになるまで待つ。
  7. APIでトポロジ、状態、L3アドレスを取得する。
  8. 必要に応じてコンソールCLIで show、ping、traceroute を実行する。
  9. 結果を results/ と logs/ に保存し、検証サマリーを作成する。
  10. 失敗した場合は設定ファイルを修正し、CML上の実機状態にも反映して再検証する。
初期完成版では、2台サンプル構成と5台BGP/VRF構成を実際にCML上へ作成し、起動、状態確認、CLI疎通確認まで実施済み。

7. 実績として構築済みの依頼

依頼フォルダ 内容 結果
requests/20260623_sample_network 2台ルーターの基本接続サンプル。IOL XEでR1/R2を構築し、IP疎通を確認。 PASS。R1からR2へのping成功。現在は停止済み。
requests/20260623_lab1_inspect 既存CMLラボ Lab1 の紐付けと状態確認。 停止済み既存ラボとして扱う。削除対象にしない。
requests/20260623_bgp_fullmesh_vrf_wan P1-P4のフルメッシュ疑似WAN、BGP、C1のBLUE/RED VRF、Loopback間疎通を構築。 PASS。通常ping、送信元指定ping、tracerouteで両方向疎通を確認済み。

8. BGP/VRF構築で反映した検証ルール

初期完成版の検証で、Loopbackを送信元指定したpingだけでは要件確認として不十分であることが分かった。 ユーザーが通常実行する ping vrf RED 172.16.101.1 や traceroute vrf RED 172.16.101.1 では、送信元がVRF側接続インターフェースになるため、WAN側に戻り経路が必要になる。

検証観点 初期完成版での扱い
Loopback送信元ping ping vrf BLUE 172.16.104.1 source 172.16.101.1 repeat 5 のように送信元Loopbackを明示して確認する。
通常ping ping vrf RED 172.16.101.1 のようにユーザーが自然に実行する形式でも確認する。
traceroute VRF内の経路が、C1、Pルーター、対向C1側IFへ到達することを確認する。
戻り経路 C1接続セグメントもWAN側で到達可能にする。BGP/VRF構成では 10.0.101.0/30 と 10.0.104.0/30 の広報を行った。

9. 制約と注意事項

10. 今後の拡張候補

候補 内容
検証レポート汎用化 cml-lab.yaml の検証項目を読み、任意構成のPASS/FAILを自動判定する。
複数行設定ツール コンソールからrunning-configへ差分投入する専用ツールを追加する。
バックアップ強化 変更前のrunning-config、CML topology、metadataを backups/ に保存する。
ワークフロー拡張 run_workflow.py で、ノード追加、リンク追加、設定投入、検証までの可視化された処理順序を広げる。
UI化 依頼フォルダ、実行状況、結果、ログを非技術者にも見やすい画面で表示する。

11. 参考情報

初期完成版では、CML APIとCML SSHコンソールサーバーを組み合わせて操作している。 CMLの画面上のWorkbenchは、本書ではCML API上のLab/Topologyと同義の操作対象として扱う。