この記事では、Diagram-as-Code ツールを使用して動的でインタラクティブなビジュアル ドキュメントを作成する方法を段階的に説明します。静的な画像の代わりに、プログラムで図を生成し、常に最新の状態に保たれ、保守が容易になります。

?コードとしての図

Diagram as Code は、従来のグラフィック ツールの代わりにコードを通じて図を作成できるアプローチです。図を手動で構築する代わりに、テキスト ファイルにコードを記述して、図の構造、コンポーネント、接続を定義できます。

このコードはグラフィック イメージに変換されるため、ソフトウェア プロジェクトへの統合と文書化が容易になります。特に、アーキテクチャ図やフロー図をプログラムで作成および更新する場合に役立ちます。

ダイアグラムとは何ですか?

Diagrams は、Diagram as Code アプローチを実装する ?Python ライブラリ で、コードを通じてアーキテクチャ インフラストラクチャ ダイアグラムやその他のタイプのダイアグラムを作成できるようにします。図を使用すると、わずか数行のコードでクラウド インフラストラクチャ コンポーネント (AWS、Azure、GCP など)、ネットワーク要素、ソフトウェア サービスなどを簡単に定義できます。

?コードとしての図の利点

• ? コードとしての図の表現: コードから直接図を作成および更新し、アジャイル プロジェクトでの保守性を確保します。
• ? 自動ドキュメント: コードからビジュアルを生成し、図を現在のアーキテクチャに合わせて維持します。
• ? 変更管理: 図の変更を経時的に追跡します。
• ? 明瞭性の向上: 明確な共有ビジュアルにより、複雑なシステムの理解を向上させます。
• ✏️ カスタマイズ可能: 柔軟でカスタマイズされたビジュアルでクラウド インフラストラクチャ、ワークフロー、またはデータ パイプラインを表現します。

チュートリアル

?ライブラリのインストール

このチュートリアルでは現在、バージョン '0.23.4' を使用しています。

!pip install diagrams=='0.23.4'

?図: ノード

このライブラリを使用すると、ノードを使用してさまざまなインフラストラクチャ コンポーネントやサービスを表すアーキテクチャ図をプログラムで作成できます。

ノードの種類

図内のノードは、さまざまなクラウド サービス プロバイダーのコンポーネントや他のアーキテクチャ要素を表します。利用可能なノードの主なカテゴリは次のとおりです:

• ☁️ クラウドプロバイダー: AWS (アマゾン ウェブ サービス)、Azure、GCP、IBM Cloud、Alibaba Cloud、Oracle Cloud、DigitalOcean など。
• ? オンプレミス: 企業の敷地内に物理的に配置されたインフラストラクチャを表します。
• ? Kubernetes (K8S): コンテナ化されたアプリケーションのデプロイ、スケーリング、管理を自動化するコンテナ オーケストレーション システム (制御とナビゲーションを象徴する船の車輪で表されます)。
• ?️ OpenStack: パブリック クラウドとプライベート クラウドを作成および管理するためのオープンソース ソフトウェア プラットフォーム。
• ? ジェネリック: プロバイダー固有のノードで特にカバーされていないコンポーネントを表すことができるジェネリック ノード (クロス ツール、1 つのカテゴリ内の異なるツールを表す)。
• ☁️ SaaS (Software as a Service): Snowflake、チャット サービス (Slack、Teams、Telegram など)、セキュリティ (Okta など) など、インターネット経由でサービスとして配信されるアプリケーションを表します。 )、またはソーシャル ネットワーク (SaaS コンセプトの電話とクラウドに取り消し線を引いたもの)。
• ? カスタム: ユーザーが特定のフォルダーに保存されている PNG アイコンを使用して図をカスタマイズできるようにします。これは、デフォルト ノード (取り消し線の付いたカスタム ツール) でカバーされていないインフラストラクチャ コンポーネントを表すのに役立ちます。

?プログラミング言語

Diagrams ライブラリを使用すると、さまざまなノードを使用してさまざまなプログラミング言語を表すことができます。これらのノードは、アーキテクチャの一部が特定のプログラミング言語で開発されたスクリプトまたはコンポーネントを利用しているかどうかを図で示すのに役立ちます。

以下に、ライブラリで利用可能なすべての言語を紹介します。不足している言語がある場合は、対応するロゴを特定のフォルダーにアップロードすることでカスタム ノードを追加できます。

# Create the diagram object
with diagrams.Diagram("Programming Languages", show=False, filename="languages"):
    # Get all the languages available in this library
    languages = [item for item in dir(diagrams.programming.language) if item[0] != '_']

    # Divide the representation in two lines
    mid_index = len(languages) // 2
    first_line = languages[:mid_index]
    second_line = languages[mid_index:]

    # Add nodes in the first row
    prev_node = None

    for language in first_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

    # Add nodes in the second row
    prev_node = None

    for language in second_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("languages.png")

☁️ AWS (アマゾン ウェブ サービス)

次のようないくつかのカテゴリに分類されている Amazon ノードを使用できます。

• 分析とビジネス: aws.analytics、aws.business
• コンピューティングとストレージ: aws.compute、aws.storage、aws.cost
• データベースと開発ツール: aws.database、aws.devtools
• 統合と管理: aws.integration、aws.management
• 機械学習とモバイル: aws.ml、aws.mobile
• ネットワーキングとセキュリティ: aws.network、aws.security
• その他: aws.blockchain、aws.enduser、aws.engagement、aws.game、aws.general、aws.iot、aws.media、aws.migration、aws.quantum、aws.robotics、aws。衛星

次に、これらのカテゴリの 1 つを表して、aws.database 内で使用可能なノードを視覚化します。

from diagrams import Diagram
from IPython.display import Image
import diagrams.aws.database as aws_database


database_components = []
for item in dir(aws_database):
    if item[0] != '_':
        if not any(comp.startswith(item) or item.startswith(comp) for comp in database_components):
            database_components.append(item)


with Diagram("AWS Database", show=False, filename="aws_database"):
    mid_index = len(database_components) // 2
    first_line = database_components[:mid_index]
    second_line = database_components[mid_index:]


    prev_node = None
    for item_database in first_line:
        current_node = eval(f"aws_database.{item_database}(item_database)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node


    prev_node = None
    for item_database in second_line:
        current_node = eval(f"aws_database.{item_database}(item_database)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("aws_database.png")

☁️ 使用例

次に、データセットのインポートと AWS での機械学習モデルのトレーニングに対応する簡単なブループリントを作成しましょう。

from diagrams import Diagram, Cluster
from diagrams.aws.storage import S3
from diagrams.aws.analytics import Glue, Athena
import diagrams.aws.ml as ml
from diagrams.aws.integration import StepFunctions
from diagrams.aws.compute import Lambda
from diagrams.aws.network import APIGateway
from IPython.display import Image

with Diagram("AWS Data Processing Pipeline", show=False):

    lambda_raw = Lambda('Get Raw Data')
    # Buckets de S3
    with Cluster("Data Lake"):
        s3_rawData = S3("raw_data")
        s3_stage = S3("staging_data")
        s3_data_capture = S3("data_capture")


    athena = Athena("Athena")
    s3_rawData >> athena
    s3_stage >> athena
    s3_data_capture >> athena

    #  Step Functions Pipeline
    with Cluster("Data Processing Pipeline"):
        step_functions = StepFunctions("Pipeline")

        # Glue Jobs in Step Functions
        with Cluster("Glue Jobs"):
            data_quality = Glue("job_data_quality")
            transform = Glue("job_data_transform")
            dataset_preparation = Glue("job_dataset_model")

        # Define Step Functions Flows
        step_functions >> data_quality >> transform >> dataset_preparation
        s3_rawData >> data_quality

    # SageMaker for model training and deployment
    with Cluster("SageMaker Model Deployment"):
        train_model = ml.SagemakerTrainingJob("job_train_model")
        eval_model = ml.SagemakerGroundTruth("job_evaluate_model")
        endpoint = ml.SagemakerModel("model_enpoint")

    # API Gateway and Lambda for the endpoint
    api_gateway = APIGateway("API_gateway")
    lambda_fn = Lambda("invoke_endpoint")

    # Connection
    lambda_raw >> s3_rawData
    s3_stage >> train_model >> eval_model >> endpoint
    endpoint >> lambda_fn >> api_gateway
    endpoint >> s3_data_capture
    dataset_preparation >> train_model


Image("aws_data_processing_pipeline.png")

リポジトリ

以下はすべてのコードへのリンクです。役に立ったと思われる場合は、スター ⭐️ を残してフォローして、新しい記事の通知を受け取ることができます。これは、テクノロジー コミュニティで成長し、より多くのコンテンツを作成するのに役立ちます。

このパイプラインを使用してドキュメント サイトを実装する方法を知りたい場合は、次のリンクで公開した記事を読むことができます

?参考文献

1. 図: https://diagrams.mingrammer.com/