terraformgraph 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

terraformgraph-1.0.4.dist-info/METADATA

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: terraformgraph
+Version: 1.0.4
+Summary: Generate interactive architecture diagrams from Terraform configurations
+Author-email: Ferdinando Bonsegna <1bonsegnaferdinando@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ferdinandobons/terraformgraph
+Project-URL: Documentation, https://github.com/ferdinandobons/terraformgraph#readme
+Project-URL: Repository, https://github.com/ferdinandobons/terraformgraph.git
+Project-URL: Issues, https://github.com/ferdinandobons/terraformgraph/issues
+Keywords: terraform,infrastructure,diagram,aws,visualization,architecture,terraformgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-hcl2>=4.3.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+# terraformgraph
+
+Generate interactive architecture diagrams from your Terraform configurations. Supports AWS resources with automatic service grouping, relationship detection, and beautiful SVG/HTML output.
+
+![Example Diagram](docs/diagram.jpg)
+
+## Features
+
+- **Automatic parsing** of Terraform HCL files with state integration
+- **Smart resource grouping** into logical services (ECS, RDS, S3, etc.)
+- **Relationship detection** based on resource references
+- **VPC structure visualization** with subnets and availability zones
+- **VPC endpoint visualization** with service-specific icons (S3, DynamoDB, ECR, etc.)
+- **Accurate resource positioning** using Terraform state
+- **Interactive HTML output** with:
+  - Drag-and-drop repositioning of service icons
+  - Click-to-highlight connections between services
+  - Click-to-highlight source and target endpoints
+  - Save/Load layout persistence
+  - Zoom and pan navigation
+- **PNG/JPG export** directly from the browser
+- **Customizable** via YAML configuration files
+- **No cloud credentials required** - works entirely offline
+
+## Prerequisites
+
+### Required
+
+- **Python 3.9+** (3.9, 3.10, 3.11, or 3.12)
+- **pip** (Python package manager)
+- **Terraform CLI** - Required for generating state JSON
+
+### Optional
+
+- **AWS Architecture Icons** - For beautiful service icons (see [With AWS Icons](#with-aws-icons))
+
+### Terraform Setup
+
+Before using terraformgraph, initialize and apply your Terraform configuration:
+
+```bash
+cd ./infrastructure
+terraform init
+terraform apply   # or terraform plan for undeployed infrastructure
+```
+
+This creates the state data that terraformgraph uses for accurate diagram generation.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install terraformgraph
+```
+
+### From Source
+
+```bash
+git clone https://github.com/ferdinandobons/terraformgraph.git
+cd terraformgraph
+pip install -e .
+```
+
+### Development Installation
+
+For contributing or running tests:
+
+```bash
+git clone https://github.com/ferdinandobons/terraformgraph.git
+cd terraformgraph
+pip install -e ".[dev]"
+```
+
+This installs additional development dependencies:
+- `pytest` - Testing framework
+- `pytest-cov` - Code coverage
+- `black` - Code formatting
+- `ruff` - Linting
+- `mypy` - Type checking
+
+## Quick Start
+
+### Basic Usage
+
+Generate a diagram from a Terraform directory:
+
+```bash
+terraformgraph -t ./infrastructure
+```
+
+This creates `terraformgraph.html` in the current directory.
+
+**Note:** The tool automatically generates state JSON from `terraform show -json` if no cached state exists. Make sure your Terraform is initialized (`terraform init`) before running.
+
+### With Environment Subdirectories
+
+If your Terraform is organized by environment:
+
+```bash
+terraformgraph -t ./infrastructure -e prod -o prod-diagram.html
+```
+
+### With Pre-generated State File
+
+If you want to generate the state file manually (useful for CI/CD):
+
+```bash
+# Generate state JSON
+cd ./infrastructure
+terraform show -json > state.json
+
+# Use it with terraformgraph
+terraformgraph -t ./infrastructure --state-file state.json
+```
+
+### Force State Refresh
+
+To regenerate the cached state file:
+
+```bash
+terraformgraph -t ./infrastructure --refresh-state
+```
+
+### With AWS Icons
+
+For beautiful AWS service icons, download the [AWS Architecture Icons](https://aws.amazon.com/architecture/icons/) and extract them:
+
+```bash
+terraformgraph -t ./infrastructure -i ./AWS_Icons
+```
+
+The tool also auto-discovers icons in these locations:
+- `./aws-official-icons`
+- `~/aws-official-icons`
+- `~/.terraformgraph/icons`
+
+## Command Line Options
+
+| Option | Short | Required | Description |
+|--------|-------|----------|-------------|
+| `--terraform` | `-t` | Yes | Path to Terraform directory |
+| `--environment` | `-e` | No | Environment subdirectory (dev, staging, prod) |
+| `--icons` | `-i` | No | Path to AWS icons directory |
+| `--output` | `-o` | No | Output HTML file path (default: `terraformgraph.html`) |
+| `--verbose` | `-v` | No | Enable debug output |
+| `--state-file` | `-s` | No | Path to pre-generated state JSON file |
+| `--refresh-state` | | No | Force regeneration of cached state file |
+
+### Examples
+
+```bash
+# Basic usage (auto-generates state)
+terraformgraph -t ./infrastructure
+
+# With environment
+terraformgraph -t ./infrastructure -e prod
+
+# With custom output
+terraformgraph -t ./infrastructure -o my-diagram.html
+
+# With AWS icons
+terraformgraph -t ./infrastructure -i ~/Downloads/AWS_Icons
+
+# With pre-generated state file
+terraformgraph -t ./infrastructure -s state.json
+
+# Force state refresh
+terraformgraph -t ./infrastructure --refresh-state
+
+# Full options with verbose output
+terraformgraph -t ./infrastructure -e prod -i ./icons -o prod.html -v
+```
+
+## How It Works
+
+1. **State Acquisition**: terraformgraph reads Terraform state (from cached file, provided file, or auto-generated via `terraform show -json`)
+2. **HCL Parsing**: Parses `.tf` files to understand resource structure and relationships
+3. **Resource Aggregation**: Groups resources into logical services (e.g., all ECS-related resources into an "ECS" service)
+4. **VPC Structure**: Builds VPC topology with availability zones, subnets, and endpoints
+5. **Layout Computation**: Calculates optimal positions for services in the diagram
+6. **HTML Generation**: Creates interactive SVG diagram with pan, zoom, and drag capabilities
+
+## Configuration
+
+### Custom Aggregation Rules
+
+Create `~/.terraformgraph/aggregation_rules.yaml` to customize how resources are grouped:
+
+```yaml
+compute:
+  my_custom_service:
+    primary: ["aws_my_resource"]
+    secondary: ["aws_my_helper"]
+    in_vpc: true
+```
+
+### Custom Connections
+
+Create `~/.terraformgraph/logical_connections.yaml` to define service relationships:
+
+```yaml
+connections:
+  - source: my_service
+    target: another_service
+    label: "Custom Connection"
+    type: data_flow
+```
+
+## Supported Resources
+
+The tool supports 100+ AWS resource types including:
+
+### Compute
+- ECS (Clusters, Services, Task Definitions)
+- EC2 (Instances, Auto Scaling Groups, Launch Templates)
+- Lambda (Functions, Layers, Event Source Mappings)
+- EKS (Clusters, Node Groups)
+- Batch (Compute Environments, Job Queues)
+
+### Networking
+- VPC (VPCs, Subnets, Route Tables, Internet Gateways)
+- VPC Endpoints (Gateway and Interface types)
+- Load Balancers (ALB, NLB, Target Groups)
+- Route53 (Zones, Records)
+- CloudFront (Distributions)
+- API Gateway (REST and HTTP APIs)
+
+### Storage
+- S3 (Buckets, Bucket Policies)
+- EBS (Volumes, Snapshots)
+- EFS (File Systems, Mount Targets)
+
+### Database
+- RDS (Instances, Clusters, Parameter Groups)
+- DynamoDB (Tables, Global Tables)
+- ElastiCache (Clusters, Replication Groups)
+- DocumentDB, Neptune, Redshift
+
+### Messaging & Integration
+- SQS (Queues)
+- SNS (Topics, Subscriptions)
+- EventBridge (Rules, Event Buses)
+- Step Functions (State Machines)
+- Kinesis (Streams, Firehose)
+
+### Security
+- IAM (Roles, Policies, Users, Groups)
+- KMS (Keys, Aliases)
+- Secrets Manager (Secrets)
+- WAF (Web ACLs, Rules)
+- Security Groups
+
+### Monitoring & Management
+- CloudWatch (Alarms, Log Groups, Dashboards)
+- CloudTrail
+- Config Rules
+
+### And many more...
+
+See the full list in the [aggregation_rules.yaml](terraformgraph/config/aggregation_rules.yaml) configuration file.
+
+## Output
+
+The generated HTML file includes:
+
+### Interactive Features
+- **Pan and Zoom** - Navigate large diagrams easily
+- **Drag-and-drop** - Reposition service icons within their containers
+- **Click connections** - Click any connection line to highlight the data flow
+- **Click services** - Click any service to see all its connections highlighted
+- **Save layout** - Persist your custom icon positions to browser storage
+- **Load layout** - Restore previously saved positions
+
+### Export Options
+- **PNG Export** - High-quality raster image
+- **JPG Export** - Compressed raster image
+
+### Visual Elements
+- **VPC containers** with subnet boundaries
+- **Availability zone indicators**
+- **Service icons** (with AWS icons or colored fallbacks)
+- **Connection lines** showing relationships
+- **Resource counts** for grouped resources
+- **Legend** with interaction instructions
+
+## Project Structure
+
+```
+terraformgraph/
+├── terraformgraph/
+│   ├── __init__.py          # Package init with version
+│   ├── __main__.py          # Entry point for python -m
+│   ├── main.py              # CLI entry point
+│   ├── parser.py            # Terraform HCL parser
+│   ├── aggregator.py        # Resource grouping logic
+│   ├── layout.py            # Diagram layout engine
+│   ├── renderer.py          # SVG/HTML renderer
+│   ├── icons.py             # AWS icon mapper
+│   ├── terraform_tools.py   # Terraform CLI integration
+│   ├── variable_resolver.py # Variable resolution
+│   └── config/              # Default configuration files
+├── tests/                   # Test suite
+├── example/                 # Example Terraform configs
+└── docs/                    # Documentation
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=terraformgraph
+
+# Run specific test file
+pytest tests/test_parser.py
+
+# Run with verbose output
+pytest -v
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest`
+5. Format code: `black terraformgraph/`
+6. Lint code: `ruff check terraformgraph/`
+7. Submit a pull request
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Author
+
+Ferdinando Bonsegna - [GitHub](https://github.com/ferdinandobons)

terraformgraph-1.0.4.dist-info/RECORD

@@ -0,0 +1,19 @@
+terraformgraph/__init__.py,sha256=P8TG3q97jSeON2wd2ZDuvPGfnU3X-hQOcpVTASlENWo,469
+terraformgraph/__main__.py,sha256=DnOv8Y0Hro-Ryc2ey3u7oLmZ2Qm_IFF5l0RNdOCLsZ0,134
+terraformgraph/aggregator.py,sha256=uV5syYVYDiy1LqtWO82yLd4LefDLB1hKsfhFtLDfoNk,40305
+terraformgraph/config_loader.py,sha256=Ue_v9MnxhlH6Ksv21QWNxSAluZ2quUgHJon173qsYdk,2204
+terraformgraph/icons.py,sha256=yn52QFB1DVvWddx0ka-Qi2NoFeMu6zdHBeQfM1wh5rQ,42315
+terraformgraph/layout.py,sha256=YBwYuL5Jxe-DCxNWQ_KANzJqPiv4v-CSAxhNb3CdfCY,27794
+terraformgraph/main.py,sha256=0NnKC4Sk3winqr-JAlTLfIM-_nmC2Nw_xzDXf0q-kEY,13462
+terraformgraph/parser.py,sha256=--ote0fkbEHgCQ2phBCbGTDdTtyH0eMGLpJeifJpxjM,23060
+terraformgraph/renderer.py,sha256=7AGb-2OGBfY2y0cKc1tgMutQFfwxnIGLv6EnTkZyje0,120850
+terraformgraph/terraform_tools.py,sha256=9hDsbMgC4imf13HMN07ADQi1c1uDPXr8bGAEDwmtFOU,12414
+terraformgraph/variable_resolver.py,sha256=vX6issc19xOB50pzeeUw-3CuzY-WYrxwg1aGw2810i8,6554
+terraformgraph/config/aggregation_rules.yaml,sha256=yqBOOHypPjww8XZr2KerJ5EQSBeHBr4twifPCBp6nXc,12555
+terraformgraph/config/logical_connections.yaml,sha256=ECOByIfuC5PStsukEkulEB8ixe4F28Q5Ak7xCs0yogA,2901
+terraformgraph-1.0.4.dist-info/licenses/LICENSE,sha256=Xy2eAxwuRwpfv90g0I3XCE_siODHZk4JSPlXZcbqQJk,1076
+terraformgraph-1.0.4.dist-info/METADATA,sha256=CskLXULXC8wD2_Tkf_Lk7Ns8eB3o75PNdY7VC9viWNU,11511
+terraformgraph-1.0.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+terraformgraph-1.0.4.dist-info/entry_points.txt,sha256=dONSqeGLyLFZCNcNjJiyLXDa23j-iwAq3u6Qtv6RI0w,60
+terraformgraph-1.0.4.dist-info/top_level.txt,sha256=iquGz8nmBrUGI8SQKJcYrq8ea7UHnBMEXRel0QuNJkI,15
+terraformgraph-1.0.4.dist-info/RECORD,,

{terraformgraph-1.0.2.dist-info → terraformgraph-1.0.4.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 [Your Name]
+Copyright (c) 2024 Ferdinando Bonsegna
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

terraformgraph-1.0.2.dist-info/METADATA

@@ -1,163 +0,0 @@
-Metadata-Version: 2.4
-Name: terraformgraph
-Version: 1.0.2
-Summary: Generate interactive architecture diagrams from Terraform configurations
-Author-email: Your Name <your.email@example.com>
-License: MIT
-Project-URL: Homepage, https://github.com/ferdinandobons/terraformgraph
-Project-URL: Documentation, https://github.com/ferdinandobons/terraformgraph#readme
-Project-URL: Repository, https://github.com/ferdinandobons/terraformgraph.git
-Project-URL: Issues, https://github.com/ferdinandobons/terraformgraph/issues
-Keywords: terraform,infrastructure,diagram,aws,visualization,architecture,terraformgraph
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Documentation
-Classifier: Topic :: System :: Systems Administration
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: python-hcl2>=4.3.0
-Requires-Dist: PyYAML>=6.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: black>=23.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
-Requires-Dist: mypy>=1.0; extra == "dev"
-Requires-Dist: types-PyYAML>=6.0; extra == "dev"
-Dynamic: license-file
-
-# terraformgraph
-
-Generate interactive architecture diagrams from your Terraform configurations. Supports AWS resources with automatic service grouping, relationship detection, and beautiful SVG/HTML output.
-
-![Example Diagram](docs/diagram.png)
-
-## Features
-
-- **Automatic parsing** of Terraform HCL files
-- **Smart resource grouping** into logical services (ECS, RDS, S3, etc.)
-- **Relationship detection** based on resource references
-- **Interactive HTML output** with drag-and-drop positioning
-- **PNG/JPG export** directly from the browser
-- **Customizable** via YAML configuration files
-- **No cloud credentials required** - works entirely offline
-
-## Installation
-
-### From PyPI
-
-```bash
-pip install terraformgraph
-```
-
-### From Source
-
-```bash
-git clone https://github.com/ferdinandobons/terraformgraph.git
-cd terraformgraph
-pip install -e .
-```
-
-## Quick Start
-
-### Basic Usage
-
-Generate a diagram from a Terraform directory:
-
-```bash
-terraformgraph -t ./infrastructure
-```
-
-This creates `diagram.html` in the current directory.
-
-### With Environment Subdirectories
-
-If your Terraform is organized by environment:
-
-```bash
-terraformgraph -t ./infrastructure -e prod -o prod-diagram.html
-```
-
-### With AWS Icons
-
-For beautiful AWS service icons, download the [AWS Architecture Icons](https://aws.amazon.com/architecture/icons/) and extract them:
-
-```bash
-terraformgraph -t ./infrastructure -i ./AWS_Icons
-```
-
-## Command Line Options
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `-t, --terraform` | Yes | Path to Terraform directory |
-| `-e, --environment` | No | Environment subdirectory (dev, staging, prod) |
-| `-i, --icons` | No | Path to AWS icons directory |
-| `-o, --output` | No | Output HTML file path (default: `diagram.html`) |
-| `-v, --verbose` | No | Enable debug output |
-
-## Configuration
-
-### Custom Aggregation Rules
-
-Create `~/.terraformgraph/aggregation_rules.yaml` to customize how resources are grouped:
-
-```yaml
-compute:
-  my_custom_service:
-    primary: ["aws_my_resource"]
-    secondary: ["aws_my_helper"]
-    in_vpc: true
-```
-
-### Custom Connections
-
-Create `~/.terraformgraph/logical_connections.yaml` to define service relationships:
-
-```yaml
-connections:
-  - source: my_service
-    target: another_service
-    label: "Custom Connection"
-    type: data_flow
-```
-
-## Supported Resources
-
-The tool supports 100+ AWS resource types including:
-
-- **Compute**: ECS, EC2, Lambda, Auto Scaling
-- **Networking**: VPC, ALB/NLB, Route53, CloudFront
-- **Storage**: S3, EBS, EFS
-- **Database**: RDS, DynamoDB, ElastiCache
-- **Messaging**: SQS, SNS, EventBridge
-- **Security**: IAM, KMS, Secrets Manager, WAF
-- **And many more...**
-
-## Output
-
-The generated HTML file includes:
-
-- **Interactive diagram** with pan and zoom
-- **Drag-and-drop** to reposition services
-- **Click connections** to highlight data flows
-- **Export buttons** for PNG and JPG
-- **Save/Load layout** using browser storage
-
-## Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.

terraformgraph-1.0.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-terraformgraph/__init__.py,sha256=fnxp13XW7PX9_BGYUGceV13yE__mbRTYmGqdS-UuxqE,469
-terraformgraph/__main__.py,sha256=E1MUfKa9LQ2_zosMoerGFHMXqWzLc9D9WO2ZUyMyN5Y,134
-terraformgraph/aggregator.py,sha256=fWTZbiwac8CEGJeQlN3X3FNAmHh5mPBsx-3dTnzaLVc,14238
-terraformgraph/config_loader.py,sha256=D5EIRqFX6Gz1BNu2b2pbG_YWqcTrUKE2iebyR58FMMo,2195
-terraformgraph/icons.py,sha256=5moYr_u4yP-Miyt0GVULavjJueZGdTwUh0W9qNJszSo,42396
-terraformgraph/layout.py,sha256=xqua1i-y3PQ_10-ZHMM43vpob87dJHbvKvs48gFp8Iw,8219
-terraformgraph/main.py,sha256=jekIKiWLbRjYGXIUaTdxnD6nInpLoX7xoHaqyqrOPPM,6668
-terraformgraph/parser.py,sha256=BDRTbQIMrTr-B_I4F17udT3hskAhN3jE5uajpp_OdZU,12525
-terraformgraph/renderer.py,sha256=mAen2OxvuH7it8pAWbO6aMS75WuW8VMSUwxufxpyJ4g,42233
-terraformgraph/config/aggregation_rules.yaml,sha256=BDkT37jCAQ0fKYqGmDJcuo6XjvfS1up5Yk1DXE4aP8M,4340
-terraformgraph/config/logical_connections.yaml,sha256=ECOByIfuC5PStsukEkulEB8ixe4F28Q5Ak7xCs0yogA,2901
-terraformgraph-1.0.2.dist-info/licenses/LICENSE,sha256=14dWZLNvm9xaUFeRin_gDB_iynn6m604g5GsutxqYsM,1068
-terraformgraph-1.0.2.dist-info/METADATA,sha256=moAQ8GUvfQ6aywg-N9FgAF5pz9FkMctkYD41Su2LZyI,4815
-terraformgraph-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-terraformgraph-1.0.2.dist-info/entry_points.txt,sha256=dONSqeGLyLFZCNcNjJiyLXDa23j-iwAq3u6Qtv6RI0w,60
-terraformgraph-1.0.2.dist-info/top_level.txt,sha256=iquGz8nmBrUGI8SQKJcYrq8ea7UHnBMEXRel0QuNJkI,15
-terraformgraph-1.0.2.dist-info/RECORD,,