terravision

テラビジョン

TerraVision は、Terraform コードを Professional Cloud Architecture Diagram に変換し、クラウド プロジェクトで最も重要なドキュメントであるアーキテクチャ ドキュメントを最新の状態に保つという問題を解決する CLI ツールです。現在、高速リリースが標準となっているため、クラウド アーキテクトが作成した現実と一致しなくなったフリースタイルの図に依存するよりも、機械で生成されたアーキテクチャ図の方が正確です。 Terravision は、Terraform への依存やクラウド環境へのアクセスなしで 100% クライアント側で安全に実行され、条件付きで作成されたリソースと変数を動的に解析し、アーキテクチャの自動ビジュアルを生成します。 Terravision は、CI/CD パイプラインに含めることができる「Docs as Code」(DaC) ツールとして設計されており、ビルド/テスト/リリース パイプライン フェーズ後にアーキテクチャ図を更新し、readthedocs.io などの他のドキュメント ジェネレーターを補完します。現在は AWS をサポートしており、まもなく Google と Azure クラウドもサポートします。

これを回して...

この中に...

このソフトウェアはまだアルファテスト中であり、コードは明示的または黙示的を問わず、いかなる種類の保証や条件もなく、「現状のまま」ベースで共有されます。ご自身の責任でご使用ください。

テラビジョンのメリット

1. 料金
   • Visio/Drawing ソフトウェアのライセンスを保存 - Terravision は無料でオープンソースです
   • クラウド リソースを起動するのにコストがかかる必要はなく、ローカル マシンから即座に動作します。
   • 定期的に図を更新し、点を並べ、接続し、アイコンを配置することは、建築家の人件費を最大限に活用するものではありません。
2. 高速化と自動化
   • TF 変数ファイルを入力として使用して、同じ TF コードから複数のバリアント図を作成します
   • Terravision を CI/CD パイプラインの一部として実行することで、アーキテクチャ図の作成を自動化します。
   • YAML ベースのコードとしての図を使用すると、生成された図に追加のカスタム ラベルやリソース (アンマネージド リソースや TF コードでキャプチャされていない外部システムなど) を使用して注釈を付けることができます。
3. 組織全体の一貫性
   • 組織/外部モジュールを自動ダウンロードして、ダウンストリーム Terraform モジュールの最新ビューを確保します
   • 業界標準のアイコンと AWS/GCP/Azure の承認済みスタイルを使用した、チーム全体でのアーキテクチャ図の一貫した設計
4. 正確な可視性
   • 図のリアルタイムの状態は、現在運用環境にデプロイされているものと正確に一致する現在のインフラストラクチャを示しています
   • サードパーティのアーキテクチャのレビュー、監査、監視、レポート作成、およびスタックのデバッグを視覚的な方法で支援します。
   • カスタム ダイアグラム コードと出力イメージをソース/バージョン管理に配置して、保守性と発見性を向上させることができます。
5. 安全
   • 図を描画するために AWS アカウントや CLI へのアクセスを許可する必要はありません
   • 企業が承認する必要があるインスタンスやメタデータ テーブルのスキャンなど、侵入的なクラウド リソースを作成しません。
   • すべてのソース コードはローカル環境に残り、図は外部 API を呼び出すことなくマシン上で生成されます。

インストールと使用方法

すべてのバージョンの外部依存関係

• グラフビズ https://graphviz.org/download/
• git https://git-scm.com/downloads
• terraform https://developer.bashicorp.com/terraform/downloads

クイックスタート

1. 上記にリストされているすべての外部依存関係をインストールします
2. リポジトリgit clone https://github.com/patrickchugh/terravision.git
3. cd terravision実行し、 pwdを実行して、作業ディレクトリ (フルパス) を取得します。
4. terravision フォルダーをPATH値に追加します (たとえば、 export PATH=$PATH:/Users/<PATH TO TERRAVISION>これにより、どこからでも実行できるようになります。 <PATH TO TERRAVISION> 3 行目の出力になります。
5. Python 要件をインストールしますcd terravision && pip install -r requirements.txt
6. terravision Python スクリプトがchmod +x terravisionで実行可能であることを確認します。
7. terravisionを実行し、Terraform ソース ファイルを次の形式で指定します。

$ terravision draw --source ~ /src/my-terraform-code

ワークスペースを含む Terraform スタックの場合、 --workspaceパラメーターを使用できます。

$ terraform draw --source ~ /src/my-terraform-code --workspace development

Git リポジトリ内の Terraform ソース コードの場合は、次のフォームを使用することもできます。

$ terravision draw --source https://github.com/your-repo/terraform-examples.git

必要なコードがフォルダー階層の下にある場合は、Git リポジトリ内のサブフォルダーに//文字を使用します。

$ terravision draw --source https://github.com/your-repo/terraform-examples.git//mysubfolder/secondfolder/

生成された図に注釈を付ける

自動生成される図には必要な詳細がすべて含まれているわけではなく、せいぜい 80 ～ 90% の作業が完了する程度です。メイン図のタイトル、矢印の追加ラベル、Terraform の外部で作成された追加リソースなどのカスタム注釈を追加するには、ソース コード フォルダーにterravision.ymlファイルを含めると、自動的に読み込まれます。あるいは、アノテーション ファイルへのパスを terravision のパラメーターとして指定します。

terravision --source https://github.com/your-repo/terraform-examples.git --annotate /Users/me/MyDocuments/annotations.yml

.yml ファイルは、次の例に似た標準の YAML 構成ファイルで、 title 、 connect 、 disconnect 、 add 、 removeまたはupdateという 1 つ以上の見出しが付いています。ノード名は、Terraform リソース名 https://registry.terraform.io/providers/bashicorp/aws/latest/docs と同じ規則に従い、ワイルドカードをサポートします。リソースの属性を変更し、 label属性 (Terraform には存在しません) を追加することで、任意の TF リソースにカスタム ラベルを追加できます。ライン/接続の場合、terravision 固有のedge_labels追加して、特定のリソース ノードへの接続ラインにテキストを追加することでリソース属性を変更できます。以下の例を参照してください。

 format : 0.1
# Main Diagram heading
title : Serverless Wordpress Site
# Draw new connection lines that are not apparent from the Terraforms
connect :
  aws_rds_cluster.this :
    - aws_ssm_parameter.db_master_user : Retrieve credentials from SSM
# Remove connections between nodes that are currently shown
disconnect :
  # Wildcards mean these disconnections apply to any cloudwatch type resource called logs
  aws_cloudwatch*.logs :
    - aws_ecs_service.this
    - aws_ecs_cluster.this
# Delete the following nodes
remove :
  - aws_iam_role.task_execution_role
# Add the following nodes
add :
  aws_subnet.another_one :
    # Specify Terraform attributes for a resource like this 
    cidr_block : " 123.123.1.1 "
# Modify attributes of existing node
update :
  aws_ecs_service.this :
    # Add custom labels to the connection lines that already exist between ECS->RDS
    edge_labels :
      - aws_rds_cluster.this : Database Queries
  # Wildcards save you listing multiple resources of the same type. This edge label is added to all CF->ACM connections.
  aws_cloudfront* :
    edge_labels :
      - aws_acm_certificate.this : SSL Cert
 # Add a custom label to a resource node. Overrides default label
  aws_ecs_service.this :
   label : " My Custom Label "

詳細なヘルプ

完全なコマンド リストまたは特定のコマンドのヘルプを表示するには、 terravision --helpと入力します。