OpenAI APIを利用してTerraformから構成図っぽいMermaidを出力してくれるコマンドを作った話

前段

※社内ブログの内容を個人発信する許可をいただいたためzennでも公開しています。

ChatGPTで話題のOpenAIのモデルは、現在画像の取り扱いはまだ発展途上です。文章から画像を作るAPIや画像入力が検討されていますが、システム運用にクリティカルに使えそうになるのはもう少し待つ必要がありそうです。

そこで現状魅力的に映るのがMermaidです^[1]。

Mermaid（マーメイド）は、テキストベースの記述によってフローチャート、シーケンス図、ガントチャートなどの図を生成するためのツールです。Mermaidは、Markdownやプレーンテキストなどのテキスト形式で図を記述し、それを自動的にグラフィカルな図に変換します。(by Chat-GPT)

画像化はJavascriptで実装されており、現在はgithubのmarkdownプレビューやNotionの専用ブロックなどで利用可能です。

Mermaidをベースにシステム運用とは切っても切り離せない作図のタスクを効率化できないかと考え、今回は「システム構成図を作るヒマがないときに、とりあえずterraformを渡せば構成図を作ってくれるAI」を目標に試行錯誤していきました。

今回の設定

提供方法はCLIに

terraformにてインフラ構成管理を行っている多くの方がterraform-docs^[2]を利用していると思います。
同じ使用感で利用できると導入がスムーズになると考え、CLIでの提供で進めます。

理想の利用イメージ

こんなことができたらいいなぁというストーリーイメージです。

1. あるスタートアップでAさんは一人でサービスの開発、運用をすべて行っている。
2. ある日新しいエンジニアの採用が決まり、ある程度システムの説明ができる必要が出てきたが、ドキュメントがまだ何も準備できていない。
3. 構成図作成コマンドを利用して構成図を作成することで5分で構成図が完成する。残った時間で必要なドキュメントを作成することができた。
4. 構成図作成コマンドはpre-commitフックに組み込まれ、今後も変更があった場合に構成図が更新される。

利用するモデル

GPT-4のwaitlistが届く気配はなく、今回はgpt3.5-turboを利用して行きます。お財布にも優しいしね！

いざ実装

CLIを作る

Go言語でフレームワークにはCobra、ビルド/公開にはgoreleaserを利用しました。
GoでのCLI開発についてはkokiさんがブログを書いてますのでぜひ参考にしてみてください^[3]。

OoenAIへのAPIコール用ライブラリは公式ではPythonとnode.jsのみの提供ですがコミュニティ開発のライブラリもドキュメントに記載されており今回はgo-openaiを利用しました^[4]。

私自身Go tourをやったことあるだけだったのですが、ChatGPTに聞きながら1日ぐらいで実装が終わりました。先駆者ｱﾘｶﾞﾀｲ。

大まかな処理チャートを以下に記載します。

プロンプト(AIへの入力)の検討

大枠が出来上がったのでOpenAIを利用するにあたり一番のミソであるプロンプトを考えていきます。

プロンプトの作成はPrompt Engineering Guide^[5]を参考に試行錯誤をしていきました。

検討フェーズでは以前私が作成したGCPで一時権限を付与できるプロジェクト^[6]のterraformを利用して行きます。構成図は以下のとおりです。

適当なプロンプトを投げてみる

何もしなくてもいいに越したことはないので以下のようなプロンプトで適当に投げてみます。
promptに記載されている<CODE>には実際には指定されたPATHのterraformのディレクトリ構成のあとに各ファイル名とその中身が出力されます。

Please create mermaid from the following terraform.

<CODE>

mermaid code block not found.

mermaidのコードがレスポンスに存在しない場合のエラー分が出力。そもそも帰ってきませんでした。プログラムをいじり、レスポンスの内容を確認します。

Sorry, as an AI language model, I cannot create a mermaid from the provided Terraform code. Can I assist you with something else?

「言語AIなので図は作れません」と来ました。ということでプロンプトの重要性がわかったところで本格的に改善していきます。

目的と背景を記載する

プロンプトエンジニアリングについて学んでいくと目的と背景を記載すると良いようです^[7]。前述の理想的な利用ケースをもとに、GOALとCONTEXT, RULEを作成してみます。
RULEにはコード部分がわかりやすいようにTEXTブロックを作成しその解説を追加してみています。

### GOAL ###
Create a highly visible system configuration diagram from terraform.

### CONTEXT ###
- You are an AI supporting an infrastructure engineer.
- The user does not have time to create a system configuration diagram to explain to his team members and would like you to do it for him.
- The only information about the current system configuration is what is described in terraform

### RULES ###.
- "### TEXT ###" will be followed by the directory structure of the terraform project. After that, "==<file_name>==" will be followed by the contents of the file in question.

### TEXT ###
<CODE>

      +-----------------+           +--------------------------+
      |    Scheduler    |           |     Secret Manager        |
      |                 |<--------->|                          |
      |  delete_expired |           |  app_user                 |
      |                 |           |  config                   |
      |                 |           |  secret_key               |
      +--------+--------+           +--------------+-----------+
               |                                       |
               v                                       v
      +--------+--------+                  +---------+---------+
      |     Cloud Run    |                  |       LB + NEG      |
      |                 |                  |                     |
      |        app      |                  |   https-proxy       |
      |                 |                  |    urlmap           |
      |                 |                  +--------+------------+
      |                 |                           |
      +---------+-------+                +----------+---------+
                |                        |   GCE Address + Cert  |
                v                        |                       |
      +---------+--------+               |  https-frontend-rule |
      |      Google       |               +---------------------+
      |       Cloud       |
      |                    |
      |    Resource        |
      |                    |
      |    Management      |
      +--------------------+

おっとMermaidという指定がなかったのでアスキーアートで図を出力してくれました。でも可能性を感じますね。さっきは作図できないといったのは嘘だったようです。

ルールを追加する

mermaidで記載するようにお願いしてみます。条件を指定する場合はしないことよりもしてほしいことを指定してあげる方が有効なようです^[8]。
ついでにIAMやsecretの情報などは構成図的に重要ではないため、そのへんは省略してもいいよと伝えてみます。

### GOAL ###
Create a highly visible system configuration diagram from terraform.

### CONTEXT ###
- You are an AI supporting an infrastructure engineer.
- The user does not have time to create a system configuration diagram to explain to his team members and would like you to do it for him.
- The only information about the current system configuration is what is described in terraform

### RULES ###.
- "### TEXT ###" will be followed by the directory structure of the terraform project. After that, "==<file_name>==" will be followed by the contents of the file in question.
- You will create a system configuration diagram using mermaid.

### TEXT ###

depends_onとあちこちに記載があり、terraform graphのようなただの依存関係の図になってしまっているようです。

手順を指定する

terraformをあまりにも意識しすぎているようなので考え方の手順を指定してみます。
terraform → mermaidではなくterraform → 構成を理解 → mermaidになってほしいという狙いです。

## GOAL ###
Create a highly visible system configuration diagram from terraform.

### CONTEXT ###
- You are an AI supporting an infrastructure engineer.
- The user does not have time to create a system configuration diagram to explain to his team members and would like you to do it for him.
- The only information about the current system configuration is what is described in terraform

### RULES ###.
- "### TEXT ###" will be followed by the directory structure of the terraform project. After that, "==<file_name>==" will be followed by the contents of the file in question.
- You will create a system configuration diagram using mermaid.
- Since it is a system configuration diagram, the detailed IAM relationships and information about the contents of Secrets are not important.
- Think in the order described in "### STEP ###".

### STEP ###
1. get an overview of the system from the information entered.
2. draw a diagram of the system overview using mermaid. 
3. Check mermaid for syntax errors.

### TEXT ###
<CODE>

完璧、、、とまでは行きませんがかなり近しい図が出てきました。少し修正すれば使えそうですね。

修正してみました。

こちらも良かった例、ブロックまで作ってくれましたが、矢印が逆を向きがちですね(これはおそらくterraformで変数の参照関係に引っ張られていると推察)。

こちらも修正かけてみました。

このあともいくつかCONTEXTをいじってみたりしましたが、これ以上改善の兆しは見えず、今回はここまでとしました。

実際にできた体験

当初考えていた体験ほど完璧な作図はできないものの、0からの作図というのは結構手間がかかりますのである程度のコスト削減は期待できるのではないかと考えています。

1. あるスタートアップでAさんは一人でサービスの開発、運用をすべて行っている。
2. ある日新しいエンジニアの採用が決まり、ある程度システムの説明ができる必要が出てきたが、ドキュメントがまだ何も準備できていない。
3. 構成図作成コマンドを利用して構成図を作成することで5分で構成図が完成する。残った時間で必要なドキュメントを作成することができた。
   1. 構成図作成コマンドである程度リソースの登場人物と関係が可視化された。矢印の向きや不要なリソースを削除して構成図が完成。0から書くよりも時間を短縮できた。
4. 構成図作成コマンドはpre-commitフックに組み込まれ、今後も変更があった場合に構成図が更新される。
   1. 正確な構成図が出る確率は極めて低いため手動で適宜更新メンテナンスをしていく。

課題と今後の展望

他のterraformプロジェクトでも実行してみたりして、主に以下のような課題があることがわかりました。

• 矢印が逆を向きがち
  • 前述の通り、terrraformの依存関係に引っ張られている様子
• ネットワークの表現が難しい
  • 今回の検討ではVPCを利用していないプロジェクトを利用しましたが、VPCを含むプロジェクトで試すとうまく表現できませんでした。
    • 具体的にはVPCの表現は多くの場合、空間で表現し、VPCのなかにsubnetがあり、subnetの中にリソースがあるという形になると思いますが、これまでの図と同様に矢印の関係にとどまってしまう。
    • Ruleに「VPCはsubgraphで表現し、所属するリソースをsubgraph内へ含めます」のような文を追加しても改善はなかなか見られませんでした。

今後、GPT-4を利用してみたらまた結果が異なると思うため、waitlistが通ることがより待ち遠しくなりました。

※同じpromptでChatGPT UI上での検証は文字数制限に引っかかってしまい検証できず

gpt-4対応時にはモデル選択オプションを追加したいです。

最後に

構成図とかいい感じにレビューしてほしいよなーという話からGPTモデルがmermaidを理解できることに気づき、今回AIにやってほしいことの1つとして試してみましたが、正直想定以上の出来でした。近い将来こういうツールが大量に生まれてくる未来を感じました。引き続きDevOps、SREの文脈での活用例を模索していきたいと思います。

少し違う視点の話ですが、今後TEXTデータであれば、AIがベースを作り人が確認するというフローが普通になっていくとDocs as Codeの重要性がより上がっていくのでは？と強く感じ、wikiサービスや作図の管理方法が変わっていくのかもしれないと妄想しています。

今回の検証で作成したレポジトリはこちらになります。
https://github.com/3-shake/terraform-imgs

参考情報

脚注

1. ChatGPTでMermaid構文を出力してみた（シーケンス図、ガントチャート、フローチャート作成の実践例）
   クラスメソッドさんでもMermaid × ChatoGPTの記事が出ています。

2. terraform-docs terraform moduleのinput, outputなどの情報を自動で表にまとめてくれるCLIツール

3. GoReleaser で Go 製 CLI のリリースを自動化＆ Homebrew でインストールできるようにする / Go でイケてる CLI を作るために利用したパッケージ

4. https://platform.openai.com/docs/libraries
   　 ※ドキュメント上はgo-gpt3と記載されておりますがレポジトリ名が更新されているため、そちらを記載しています

5. Prompt Engineering Guide

6. Google Cloud上で簡易的な高権限管理を実現する

7. Prompt Engineering Guide| プロンプトの要素

8. Prompt Engineering Guide | プロンプトの設計に関する一般的なヒント | するか？しないか？