Metadata-Version: 2.1
Name: drawtf
Version: 0.5.0
Summary: Draw diagrams from tf state files
Home-page: https://github.com/Aggreko/DrawTF
Author: Aggreko
Author-email: michael.law@aggreko.com
License: MIT license
Description: [![PyPI Version](https://img.shields.io/pypi/v/drawtf.svg)](https://pypi.python.org/project/drawtf) ![Latest Build](https://github.com/aggreko/drawtf/actions/workflows/main.yml/badge.svg)
        
        # drawtf
        Draw diagrams which include Cloud resources using TF state files or without them. Inspired by the [Diagrams](https://github.com/mingrammer/diagrams) package and a burning desire to not have to manually keep architecture diagrams updated, this was born.
        
        ## Prerequisites
        * Install Python
        * Install [Graphviz](https://graphviz.org/)
          
        ## Install
        ```console
        foo@bar:~$ python -m pip install --upgrade pip
        foo@bar:~$ pip install drawtf
        foo@bar:~$ drawtf --help
        
        Usage: drawtf [OPTIONS]
        
          Console script for drawtf.
        
        Options:
          --name TEXT                     The diagram name.
          --state TEXT                    The tfstate file to run against.
          --platform TEXT                 The platform to use 'azure' or 'aws', only
                                          'azure' currently supported
        
          --output-path TEXT              Output path if to debug generated json    
                                          populated.
        
          --json-config-path TEXT         Config file path if populated.
          --json-config-override-path TEXT
                                          Config file with overrides path to merge  
                                          with main one if populated.
        
          --verbose                       Add verbose logs.
          --help                          Show this message and exit.
        ```
        
        ## Usage
        There are a few ways we can create diagrams here, all options on the CLI are optional, and it is basically just the order which you create them that draws a diagram.
        
        ### Sample config File (app.json)
        If we use a config file with the fields below, this will set the name for the designs title, import a state file, and add some custom components not in the state file, The final section at the bottom draws the lines between the resources.
        
        ```json 
        {
            "name": "Aggreko Application (All Resources)",
            "state": "../../application.tfstate",
            "components": [
                {
                    "name": "Aggreko",
                    "type": "draw_custom",
                    "resource_group_name": "",
                    "attributes":{},
                    "components": [
                        {
                            "name": "InternalDB",
                            "type": "draw_custom",
                            "resource_group_name": "",
                            "custom": "diagrams.azure.database.DatabaseForMysqlServers",
                            "attributes": {}
                        },
                        {
                            "name": "App",
                            "type": "draw_custom",
                            "resource_group_name": "",
                            "custom": "diagrams.onprem.compute.Server",
                            "attributes": {}
                        },
                        {
                            "name": "AnotherApp",
                            "type": "draw_custom",
                            "resource_group_name": "",
                            "custom": "diagrams.onprem.compute.Server",
                            "attributes": {}
                        }
                    ]
                }
            ],
        	"links": [
                {
                    "from": "App-draw_custom",
                    "to": "InternalDB-draw_custom",
                    "color": "darkgreen",
                    "label": "Write",
                    "type": "dotted"
                },
                {
                    "from": "AnotherApp-draw_custom",
                    "to": "InternalDB-draw_custom",
                    "color": "darkgreen",
                    "label": "Write",
                    "type": "dotted"
                }
            ],
            "excludes": []
        }                                            
        ```
        
        ```console 
        foo@bar:~$ drawtf --json-config-path ./test/app.json    
        ``` 
        ![Example](https://github.com/aggreko/drawtf/blob/main/test/app.png?raw=true)
        
        By running the command above pointing to the config file, this will set the name and grab other resources from the state file linked. Outputs from will create the design in the same sub-folder with the name **app.png**.
        
        ### Override config File (app-subset.json)
        
        Providing an override config alongside our main config file with the fields below, this will override the initial the designs title but still use the same state file and components from the original and attempt to join the links if all of the resources are available. You will notice an excludes section, if the keys for each resource added are in this list, then it will exclude those items.
        
        ```json
        {
            "name": "Aggreko Application (Subset)",
            "excludes": [ 
                "AnotherApp-draw_custom"
            ]
        }  
        ```
        
        ```console 
        foo@bar:~$ drawtf --json-config-path ./test/app.json --json-config-override-path ./test/app-subset.json
        ```
        ![Example](https://github.com/aggreko/drawtf/blob/main/test/app-subset.png?raw=true)
        
        By running the command above pointing to the config file and override files, this will set the name from the override and grab other resources from the state file linked. Outputs from will create the design in the same sub-folder with the name **app-subset.png**.
        
        ### Override config File and CLI overrides
        
        ```console 
        foo@bar:~$ drawtf --json-config-path ./test/app.json --json-config-override-path ./test/app-subset.json --name "Aggreko Application (Sample)" --state ./test/app.tfstate --output-path ./test/sample --verbose                                                                           
        ```
        ![Example](https://github.com/aggreko/drawtf/blob/main/test/sample.png?raw=true)
        
        The command above, though using the same config files, can override all for the name, state file path and output path. Outputs from will create the design in the directory **test** with the name **sample.png**.
        
        ## Github Actions Steps
        
        Yes you can run this via GitHub actions or devops pipelines.
        
        ```yaml
              - name: Setup Graphviz
                uses: ts-graphviz/setup-graphviz@v1
              - name: Set up Python 3.7
                uses: actions/setup-python@v4
                with:
                  python-version: '3.7'
              - name: Generate Diagram
                run: |
                  python -m pip install --upgrade pip
                  pip install drawtf
                  drawtf --help
                  drawtf --json-config-path "./static/images/test/test.json"
        ```
        
        ## Early days
        
        Just an FYI, its early days here and is still a development style project. That said we are using for all of our projects internally using TF, but loads of resources types are still to be added.
Keywords: drawtf,terraform,ci/cd,design,architecture,diagrams,graphviz
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.7
Description-Content-Type: text/markdown
