[](https://pypi.python.org/project/drawtf) 
# 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]
Top level command for drawtf.
Options:
--help Show this message and exit.
Commands:
draw Draw a single design from config and settings.
watch Watch a directory for changes to draw.
foo@bar:~$ drawtf draw --help
Usage: drawtf draw [OPTIONS]
Draw a single design from config and settings.
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.
--verbose Add verbose logs.
--help Show this message and exit.
foo@bar:~$ drawtf watch --help
Usage: drawtf watch [OPTIONS]
Watch a directory for changes to draw.
Options:
--directory TEXT Directory to watch for changes in.
--help Show this message and exit.
```
## Draw
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": "./test/app.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 draw --json-config-path ./test/app.json
```
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)",
"base": ".//test//app.json",
"excludes": [
"AnotherApp-draw_custom"
]
}
```
```console
foo@bar:~$ drawtf draw --json-config-path ./test/app-subset.json
```
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 draw --json-config-path ./test/app-subset.json --name "Aggreko Application (Sample)" --state ./test/app.tfstate --output-path ./test/sample --verbose
```
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**.
## Watch
It is now possible to simply watch a folder for *.json files to change or be created, this will then pick up the changes and draw designs as required.
```console
foo@bar:~$ drawtf watch --directory ./test
Starting watch for *.json files...
Watching in .//test...
Modified file .//test\app.json, drawing...
Adding resource APPLICATION_DEV-azurerm_resource_group
Adding resource storageaccount-azurerm_storage_account
Adding resource (from config) InternalDB-draw_custom
Adding resource (from config) App-draw_custom
Adding resource (from config) AnotherApp-draw_custom
Adding resource (from config) Aggreko-draw_custom
.//test\app.json done.
Modified file .//test\app-subset.json, drawing...
Adding resource APPLICATION_DEV-azurerm_resource_group
Adding resource storageaccount-azurerm_storage_account
Adding resource (from config) InternalDB-draw_custom
Adding resource (from config) App-draw_custom
Excluding resource (from config) AnotherApp-draw_custom
Adding resource (from config) Aggreko-draw_custom
WARNING:root:Ignoring link as object not in component cache: {'from': 'AnotherApp-draw_custom', 'to': 'InternalDB-draw_custom', 'color': 'firebrick', 'label': 'Write', 'type': 'dotted'}
.//test\app-subset.json done.
```
## CI/CD Steps
Yes you can run this via GitHub actions or devops pipelines.
### GitHub Actions
```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 draw --json-config-path "./test/app.json"
```
### Azure Devops
```yaml
- script: sudo apt-get -yq install graphviz
displayName: Setup Graphviz
- script: |
python -m pip install --upgrade pip
pip install drawtf
drawtf --help
drawtf draw --json-config-path "./test/app.json"
displayName: Generate Diagram
```
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/AggrekoTechnologyServices/DrawTF",
"name": "drawtf",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "drawtf,terraform,ci/cd,design,architecture,diagrams,graphviz",
"author": "Aggreko",
"author_email": "michael.law@aggreko.com",
"download_url": "https://files.pythonhosted.org/packages/3c/83/a34e4b04d5e7d2f5325c14f974d3a138a9059b0ab6baf711644a0834c38d/drawtf-0.12.0.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/project/drawtf) \n\n# drawtf\nDraw 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.\n\n## Prerequisites\n* Install Python\n* Install [Graphviz](https://graphviz.org/)\n\n## Install\n```console\nfoo@bar:~$ python -m pip install --upgrade pip\nfoo@bar:~$ pip install drawtf\nfoo@bar:~$ drawtf --help\n\nUsage: drawtf [OPTIONS]\n\n Top level command for drawtf.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n draw Draw a single design from config and settings.\n watch Watch a directory for changes to draw.\n\nfoo@bar:~$ drawtf draw --help\n\nUsage: drawtf draw [OPTIONS]\n\n Draw a single design from config and settings.\n\nOptions:\n --name TEXT The diagram name.\n --state TEXT The tfstate file to run against.\n --platform TEXT The platform to use 'azure' or 'aws', only 'azure'\n currently supported\n\n --output-path TEXT Output path if to debug generated json populated.\n --json-config-path TEXT Config file path if populated.\n --verbose Add verbose logs.\n --help Show this message and exit.\n\nfoo@bar:~$ drawtf watch --help\n\nUsage: drawtf watch [OPTIONS]\n\n Watch a directory for changes to draw.\n\nOptions:\n --directory TEXT Directory to watch for changes in.\n --help Show this message and exit.\n```\n\n## Draw\nThere 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.\n\n### Sample config File (app.json)\nIf 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.\n\n```json \n{\n \"name\": \"Aggreko Application (All Resources)\",\n \"state\": \"./test/app.tfstate\",\n \"components\": [\n {\n \"name\": \"Aggreko\",\n \"type\": \"draw_custom\",\n \"resource_group_name\": \"\",\n \"attributes\":{},\n \"components\": [\n {\n \"name\": \"InternalDB\",\n \"type\": \"draw_custom\",\n \"resource_group_name\": \"\",\n \"custom\": \"diagrams.azure.database.DatabaseForMysqlServers\",\n \"attributes\": {}\n },\n {\n \"name\": \"App\",\n \"type\": \"draw_custom\",\n \"resource_group_name\": \"\",\n \"custom\": \"diagrams.onprem.compute.Server\",\n \"attributes\": {}\n },\n {\n \"name\": \"AnotherApp\",\n \"type\": \"draw_custom\",\n \"resource_group_name\": \"\",\n \"custom\": \"diagrams.onprem.compute.Server\",\n \"attributes\": {}\n }\n ]\n }\n ],\n\t\"links\": [\n {\n \"from\": \"App-draw_custom\",\n \"to\": \"InternalDB-draw_custom\",\n \"color\": \"darkgreen\",\n \"label\": \"Write\",\n \"type\": \"dotted\"\n },\n {\n \"from\": \"AnotherApp-draw_custom\",\n \"to\": \"InternalDB-draw_custom\",\n \"color\": \"darkgreen\",\n \"label\": \"Write\",\n \"type\": \"dotted\"\n }\n ],\n \"excludes\": []\n} \n```\n\n```console \nfoo@bar:~$ drawtf draw --json-config-path ./test/app.json \n``` \n\n\nBy 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**.\n\n### Override config File (app-subset.json)\n\nProviding 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.\n\n```json\n{\n \"name\": \"Aggreko Application (Subset)\",\n \"base\": \".//test//app.json\",\n \"excludes\": [ \n \"AnotherApp-draw_custom\"\n ]\n} \n```\n\n```console \nfoo@bar:~$ drawtf draw --json-config-path ./test/app-subset.json\n```\n\n\nBy 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**.\n\n### Override config File and CLI overrides\n\n```console \nfoo@bar:~$ drawtf draw --json-config-path ./test/app-subset.json --name \"Aggreko Application (Sample)\" --state ./test/app.tfstate --output-path ./test/sample --verbose \n```\n\n\nThe 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**.\n\n## Watch\n\nIt is now possible to simply watch a folder for *.json files to change or be created, this will then pick up the changes and draw designs as required.\n\n```console\nfoo@bar:~$ drawtf watch --directory ./test \n\nStarting watch for *.json files...\nWatching in .//test...\nModified file .//test\\app.json, drawing...\nAdding resource APPLICATION_DEV-azurerm_resource_group\nAdding resource storageaccount-azurerm_storage_account\nAdding resource (from config) InternalDB-draw_custom\nAdding resource (from config) App-draw_custom\nAdding resource (from config) AnotherApp-draw_custom\nAdding resource (from config) Aggreko-draw_custom\n.//test\\app.json done.\nModified file .//test\\app-subset.json, drawing...\nAdding resource APPLICATION_DEV-azurerm_resource_group\nAdding resource storageaccount-azurerm_storage_account\nAdding resource (from config) InternalDB-draw_custom\nAdding resource (from config) App-draw_custom\nExcluding resource (from config) AnotherApp-draw_custom\nAdding resource (from config) Aggreko-draw_custom\nWARNING:root:Ignoring link as object not in component cache: {'from': 'AnotherApp-draw_custom', 'to': 'InternalDB-draw_custom', 'color': 'firebrick', 'label': 'Write', 'type': 'dotted'}\n.//test\\app-subset.json done.\n```\n\n## CI/CD Steps\n\nYes you can run this via GitHub actions or devops pipelines.\n\n### GitHub Actions\n\n```yaml\n - name: Setup Graphviz\n uses: ts-graphviz/setup-graphviz@v1\n - name: Set up Python 3.7\n uses: actions/setup-python@v4\n with:\n python-version: '3.7'\n - name: Generate Diagram\n run: |\n python -m pip install --upgrade pip\n pip install drawtf\n drawtf --help\n drawtf draw --json-config-path \"./test/app.json\"\n```\n\n### Azure Devops\n\n```yaml\n - script: sudo apt-get -yq install graphviz\n displayName: Setup Graphviz\n - script: |\n python -m pip install --upgrade pip\n pip install drawtf\n drawtf --help\n drawtf draw --json-config-path \"./test/app.json\"\n displayName: Generate Diagram\n```\n\n## Early days\n\nJust 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.\n\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Draw diagrams from tf state files",
"version": "0.12.0",
"project_urls": {
"Homepage": "https://github.com/AggrekoTechnologyServices/DrawTF"
},
"split_keywords": [
"drawtf",
"terraform",
"ci/cd",
"design",
"architecture",
"diagrams",
"graphviz"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b8f5bd2a856007e33ad9e64155e8445823b8e6679e7c6ea24a9bfc3def36e1f",
"md5": "0d3bcd3c1eb458924c0265e08bde9b3c",
"sha256": "9c34873b736ee9ba067691be895e2bc2ac2167430898c904a1b07d9a82865f67"
},
"downloads": -1,
"filename": "drawtf-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0d3bcd3c1eb458924c0265e08bde9b3c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 45554,
"upload_time": "2023-09-10T21:57:43",
"upload_time_iso_8601": "2023-09-10T21:57:43.203735Z",
"url": "https://files.pythonhosted.org/packages/2b/8f/5bd2a856007e33ad9e64155e8445823b8e6679e7c6ea24a9bfc3def36e1f/drawtf-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3c83a34e4b04d5e7d2f5325c14f974d3a138a9059b0ab6baf711644a0834c38d",
"md5": "52ca94aed3cc23e68d56819886d115f4",
"sha256": "a2ebc8163980ebb98b002b690303c2100e06fdbfeecec8d4b51c9cec73785d73"
},
"downloads": -1,
"filename": "drawtf-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "52ca94aed3cc23e68d56819886d115f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21944,
"upload_time": "2023-09-10T21:57:44",
"upload_time_iso_8601": "2023-09-10T21:57:44.974873Z",
"url": "https://files.pythonhosted.org/packages/3c/83/a34e4b04d5e7d2f5325c14f974d3a138a9059b0ab6baf711644a0834c38d/drawtf-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-10 21:57:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AggrekoTechnologyServices",
"github_project": "DrawTF",
"github_not_found": true,
"lcname": "drawtf"
}
JSON
