Generate OCI architecture diagrams using Diagrams

What are Diagrams

Diagrams are OSS that generate files of various architecture diagrams by writing code in Python. The version at the time of publication of this article is 0.6.2.

It is possible to generate architecture diagrams for on-premises, Kubernetes, AWS, Azure, GCP, Alibaba Cloud, as well as Oracle Cloud, and a mixture of these. This article is based on OCI, but the basic usage is the same for architecture diagrams other than OCI, except that the packages to be imported are different. The generated architecture diagram will be different from that of various cloud standards, but I think that it is possible to realize version control of the architecture diagram based on the "Diagram as Code", which is also sung on the original site. The license is the MIT license.

Diagrams site GitHub

Introduction of Diagrams

Introduction of Graphviz

Diagrams rely on an OSS called Graphviz to depict diagrams. To use Diagrams, you need to install Graphviz first. If you are using Homebrew on your Mac, you can install it with brew install graphviz. For Windows, download and install the software from the Graphviz site. Also, pass the path to the installation path \ bin.

Introduction of Diagrams

It can be installed with pip install diagrams in Python3.6 or higher environment.

Execution sample and explanation

Architectural diagram output example

This time, I will output the following sample. As in the example, Japanese is also available.

Coding sample

sample.py

from diagrams import Cluster, Diagram
from diagrams.oci.compute import Vm as VM
from diagrams.oci.database import Databaseservice as DBCS
from diagrams.oci.network import Loadbalance as LB, Drg as DRG
from diagrams.oci.connectivity import Fastconnect as FC

with Diagram("OCI sample architecture diagram", outformat="pdf", filename="oci_sample", show=False):
    with Cluster("Sample VCN"):
        drg = DRG("DRG")
        with Cluster("Private Subnet"):
            lb = LB("Load Balancer")
            ap = [VM("Application\nServer2"), VM("Application\nServer1")]
            db = DBCS("Database Server")
    FC("FastConnect") >> drg >> lb >> ap >> db

Basic concept

Diagrams have the basic concepts of Diagram, Node, and Cluster. Diagram A class of architecture diagrams. Since the Diagram class supports the with statement, it can be described like a sample. Below is a description of the sample source arguments.

--name: The first argument. The argument name is omitted in the sample code. Specify the title of the diagram. --outformat: Specify the format of the output file. The default when not specified is png. Besides, it supports jpg, svg, and pdf. --filename: Specify the output file name. If not specified, the default is the figure title converted to lowercase. --show: Use bool to specify whether to display the output file in the standard viewer. The default is True.

The following arguments can be specified in addition to those specified in the sample.

--direction: Specifies the direction of the flow. The following 4 types can be specified. --LR: Left to right (default) --RL: Right to left --TB: Top to bottom --BT: From bottom to top --graph_attr, node_attr, edge_attr: Specify the architecture diagram, Node (described later), and edge format in JSON format, respectively. The contents that can be specified are those supported by Graphviz. Please refer to Explanation of Graphviz for the details of the contents that can be specified.

Node A class of nodes (instances, services, etc.). In the sample diagram, the parts that are "DRG" or "Database Server" are applicable. Node object names are in the format "provider.resource type.name". See here for a list of Nodes. The only argument is label. --label: The argument name is omitted in the sample code. Specify the title of the node.

Cluster A class that groups Nodes. The sample figure uses Cluster to represent VCNs and subnets. It is also possible to nest Clusters as shown in the sample figure. There is no particular limit to the number of nesting layers. It is also possible to display multiple Clusters in the same hierarchy. Below is a description of the arguments. --label: The first argument. The argument name is omitted in the sample code. Specify the title of the grouping. If not specified, "cluster" is displayed. --direction: Same as the direction argument of Diagram.

Coding flow

Basically, just create an instance of Node to be displayed in the with statement of the Diagram class, arrange them in the display order, and specify the direction of the line connecting the Nodes. Specify Cluster if necessary, and Node belonging to the cluster will be generated in the with statement of Cluster. There are three types of line directions as follows.

->>: Arrow from front to back -<<: Arrow from back to front ----: Line without arrow

Finally

Overall, if you're familiar with Python, you'll probably understand it after a while looking at the coding sample, except for the argument explanations. At the time of writing the article, it seems that the coverage of the supported services is a little weak, but Diagrams are being actively updated, and it is expected that it will evolve further.