runbooks 0.6.1__py3-none-any.whl → 0.7.5__py3-none-any.whl

runbooks/finops/README.md

@@ -0,0 +1,337 @@
+# AWS FinOps Dashboard (CLI)
+
+The AWS FinOps Dashboard is an open-source, Python-based command-line tool (built with the Rich library) for AWS cost monitoring. It provides multi-account cost summaries by time period, service, and cost allocation tags; budget limits vs. actuals; EC2 instance status; six‑month cost trend charts; and “FinOps audit” reports (e.g. untagged or idle resources). It can export data to CSV/JSON/PDF.
+
+## Why AWS FinOps Dashboard?
+
+Managing and understanding your AWS expenditure, especially across multiple accounts and services, can be complex. The AWS FinOps Dashboard CLI aims to simplify this by providing a clear, concise, and actionable view of your AWS costs and operational hygiene directly in your terminal.
+
+Key features include:
+*   **Unified View:** Consolidate cost and resource data from multiple AWS accounts.
+![alt text](runbooks finops-v2.2.3.png)
+* **Cost Trend Analysis:** View how your AWS costs have been for the past six months.
+![alt text](runbooks finops-dashboard_trend.png)
+*   **Audit Your AWS Accounts:** Quickly identify spending patterns, untagged resources, underutilised resources and potential savings.
+![alt text](audit_report.png)
+*   **Generate Cost & Audit Reports:** You can generate Cost, Trend and Audit Reports in PDF, CSV & JSON formats for further analysis and reporting purposes.
+![alt text](audit_report_pdf.png)
+![alt text](cost_report_pdf.png)
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [AWS CLI Profile Setup](#aws-cli-profile-setup)
+- [Command Line Usage](#command-line-usage)
+  - [Options](#command-line-options)
+  - [Examples](#examples)
+- [Using a Configuration File](#using-a-configuration-file)
+  - [TOML Configuration Example (`config.toml`)](#toml-configuration-example-configtoml)
+  - [YAML Configuration Example (`config.yaml` or `config.yml`)](#yaml-configuration-example-configyaml-or-configyml)
+  - [JSON Configuration Example (`config.json`)](#json-configuration-example-configjson)
+- [Export Formats](#export-formats)
+- [Cost For Every Run](#cost-for-every-run)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **Cost Analysis by Time Period**: 
+  - View current & previous month's spend by default
+  - Set custom time ranges (e.g., 7, 30, 90 days) with `--time-range` option
+- **Cost by AWS Service**: Sorted by highest cost for better insights
+- **Cost by Tag**: Get the cost data by one or more tags with `--tag`(cost allocation tags must be enabled)
+- **AWS Budgets Information**: Displays budget limits and actual spend
+- **EC2 Instance Status**: Detailed state information across specified/accessible regions
+- **Cost Trend Analysis**: View detailed cost trends in bar charts for the last 6 months across AWS profiles
+- **FinOps Audit**: View untagged resources, unused or stopped resources, and Budget breaches across AWS profiles. 
+- **Profile Management**:
+  - Automatic profile detection
+  - Specific profile selection with `--profiles`
+  - Use all available profiles with `--all`
+  - Combine profiles from the same AWS account with `--combine`
+- **Region Control**: Specify regions for EC2 discovery using `--regions`
+- **Export Options**:
+  - CSV export with `--report-name` and `--report-type csv`
+  - JSON export with `--report-name` and `--report-type json`
+  - PDF export with `--report-name` and `--report-type pdf`
+  - Export to both CSV and JSON formats with `--report-name` and `--report-type csv json`
+  - Specify output directory using `--dir`
+  - **Note**: Trend reports (generated via `--trend`) currently only support JSON export. Other formats specified in `--report-type` will be ignored for these reports.
+- **Improved Error Handling**: Resilient and user-friendly error messages
+- **Beautiful Terminal UI**: Styled with the Rich library for a visually appealing experience
+
+---
+
+## Prerequisites
+
+- **Python 3.8 or later**: Ensure you have the required Python version installed
+- **AWS CLI configured with named profiles**: Set up your AWS CLI profiles for seamless integration
+- **AWS credentials with permissions**:
+  - `ce:GetCostAndUsage`
+  - `budgets:ViewBudget`
+  - `ec2:DescribeInstances`
+  - `ec2:DescribeRegions`
+  - `sts:GetCallerIdentity`
+  - `ec2:DescribeInstances`
+  - `ec2:DescribeVolumes`
+  - `ec2:DescribeAddresses`
+  - `rds:DescribeDBInstances`
+  - `rds:ListTagsForResource`
+  - `lambda:ListFunctions`
+  - `lambda:ListTags`
+  - `elbv2:DescribeLoadBalancers`
+  - `elbv2:DescribeTags`
+  
+---
+
+## AWS CLI Profile Setup
+
+If you haven't already, configure your named profiles using the AWS CLI:
+
+```bash
+aws configure --profile profile1-name
+aws configure --profile profile2-name
+# ... etc ...
+```
+
+Repeat this for all the profiles you want the dashboard to potentially access.
+
+---
+
+## Command Line Usage
+
+Run the script using `runbooks finops` followed by options:
+
+```bash
+runbooks finops [options]
+```
+
+### Command Line Options
+
+| Flag | Description |
+|---|---|
+| `--config-file`, `-C` | Path to a TOML, YAML, or JSON configuration file. Command-line arguments will override settings from the config file. |
+| `--profiles`, `-p` | Specific AWS profiles to use (space-separated). If omitted, uses 'default' profile if available, otherwise all profiles. |
+| `--regions`, `-r` | Specific AWS regions to check for EC2 instances (space-separated). If omitted, attempts to check all accessible regions. |
+| `--all`, `-a` | Use all available AWS profiles found in your config. |
+| `--combine`, `-c` | Combine profiles from the same AWS account into single rows. |
+| `--tag`, `-g` | Filter cost data by one or more cost allocation tags in `Key=Value` format. Example: `--tag Team=DevOps Env=Prod` |
+| `--report-name`, `-n` | Specify the base name for the report file (without extension). |
+| `--report-type`, `-y` | Specify report types (space-separated): 'csv', 'json', 'pdf'. For reports generated with `--audit`, only 'pdf' is applicable and other types will be ignored. |
+| `--dir`, `-d` | Directory to save the report file(s) (default: current directory). |
+| `--time-range`, `-t` | Time range for cost data in days (default: current month). Examples: 7, 30, 90. |
+| `--trend` | View cost trend analysis for the last 6 months. |
+| `--audit` | View list of untagged, unused resoruces and budget breaches. |
+
+### Examples
+
+```bash
+# Use default profile, show output in terminal only
+runbooks finops
+
+# Use specific profiles 'dev' and 'prod'
+runbooks finops --profiles dev prod
+
+# Use all available profiles
+runbooks finops --all
+
+# Combine profiles from the same AWS account
+runbooks finops --all --combine
+
+# Specify custom regions to check for EC2 instances
+runbooks finops --regions us-east-1 eu-west-1 ap-southeast-2
+
+# View cost data for the last 30 days instead of current month
+runbooks finops --time-range 30
+
+# View cost data only for a specific tag (e.g., Team=DevOps)
+runbooks finops --tag Team=DevOps
+
+# View cost data for multiple tags (e.g., Team=DevOps and Env=Prod)
+runbooks finops --tag Team=Devops Env=Prod
+
+# Export data to CSV only
+runbooks finops --all --report-name aws_dashboard_data --report-type csv
+
+# Export data to JSON only
+runbooks finops --all --report-name aws_dashboard_data --report-type json
+
+# Export data to both CSV and JSON formats simultaneously
+runbooks finops --all --report-name aws_dashboard_data --report-type csv json
+
+# Export combined data for 'dev' and 'prod' profiles to a specific directory
+runbooks finops --profiles dev prod --combine --report-name report --report-type csv --dir output_reports
+
+# View cost trend analysis as bar charts for profile 'dev' and 'prod'
+runbooks finops --profiles dev prod -r us-east-1 --trend
+
+# View cost trend analysis for all cli profiles for a specific cost tag 'Team=DevOps'
+runbooks finops --all --trend --tag Team=DevOps
+
+# View audit report for profile 'dev' in region 'us-east-1'
+runbooks finops -p dev -r us-east-1 --audit
+
+# View audit report for profile 'dev' in region 'us-east-1' and export it as a pdf file to current working dir with file name 'Dev_Audit_Report'
+runbooks finops -p dev -r us-east-1 --audit -n Dev_Audit_Report -y pdf
+
+# Use a configuration file for settings
+runbooks finops --config-file path/to/your_config.toml
+# or
+runbooks finops -C path/to/your_config.yaml
+```
+
+You'll see a live-updating table of your AWS account cost and usage details in the terminal. If export options are specified, a report file will also be generated upon completion.
+
+---
+
+## Using a Configuration File
+
+Instead of passing all options via the command line, you can use a configuration file in TOML, YAML, or JSON format. Use the `--config-file` or `-C` option to specify the path to your configuration file.
+
+Command-line arguments will always take precedence over settings defined in the configuration file.
+
+Below are examples of how to structure your configuration file.
+
+### TOML Configuration Example (`config.toml`)
+
+```toml
+# config.toml
+profiles = ["dev-profile", "prod-profile"]
+regions = ["us-east-1", "eu-west-2"]
+combine = true
+report_name = "monthly_finops_summary"
+report_type = ["csv", "pdf"] # For cost dashboard. For audit, only PDF is used.
+dir = "./reports/runbooks finops" # Defaults to present working directory
+time_range = 30 # Defaults to 30 days
+tag = ["CostCenter=Alpha", "Project=Phoenix"] # Optional
+audit = false # Set to true to run audit report by default
+trend = false # Set to true to run trend report by default
+```
+
+### YAML Configuration Example (`config.yaml` or `config.yml`)
+
+```yaml
+# config.yaml
+profiles:
+  - dev-profile
+  - prod-profile
+regions:
+  - us-east-1
+  - eu-west-2
+combine: true
+report_name: "monthly_finops_summary"
+report_type:
+  - csv
+  - pdf # For cost dashboard. For audit, only PDF is used.
+dir: "./reports/runbooks finops"
+time_range: 30
+tag:
+  - "CostCenter=Alpha"
+  - "Project=Phoenix"
+audit: false # Set to true to run audit report by default
+trend: false # Set to true to run trend report by default
+```
+
+### JSON Configuration Example (`config.json`)
+
+```json
+{
+  "profiles": ["dev-profile", "prod-profile"],
+  "regions": ["us-east-1", "eu-west-2"],
+  "combine": true,
+  "report_name": "monthly_finops_summary",
+  "report_type": ["csv", "pdf"], /* For cost dashboard. For audit, only PDF is used. */
+  "dir": "./reports/runbooks finops",
+  "time_range": 30,
+  "tag": ["CostCenter=Alpha", "Project=Phoenix"],
+  "audit": false, /* Set to true to run audit report by default */
+  "trend": false /* Set to true to run trend report by default */
+}
+```
+---
+
+## Export Formats
+
+### CSV Output Format
+
+When exporting to CSV, a file is generated with the following columns:
+
+- `CLI Profile`
+- `AWS Account ID`
+- `Last Month Cost` (or previous period based on time range)
+- `Current Month Cost` (or current period based on time range)
+- `Cost By Service` (Each service and its cost appears on a new line within the cell)
+- `Budget Status` (Each budget's limit and actual spend appears on a new line within the cell)
+- `EC2 Instances` (Each instance state and its count appears on a new line within the cell)
+
+**Note:** Due to the multi-line formatting in some cells, it's best viewed in spreadsheet software (like Excel, Google Sheets, LibreOffice Calc) rather than plain text editors.
+
+### JSON Output Format
+
+When exporting to JSON, a structured file is generated that includes all dashboard data in a format that's easy to parse programmatically.
+
+### PDF Output Format (for Audit Report)
+
+When exporting to PDF, a file is generated with the following columns:
+
+- `Profile`
+- `Account ID`
+- `Untagged Resources`
+- `Stopped EC2 Instances`
+- `Unused Volumes`
+- `Unused EIPs`
+- `Budget Alerts`
+
+---
+
+## Cost For Every Run
+
+This script makes API calls to AWS, primarily to Cost Explorer, Budgets, EC2, and STS. AWS may charge for Cost Explorer API calls (typically `$0.01` for each API call, check current pricing).
+
+The number of API calls depends heavily on the options used:
+
+- **Default dashboard when `--audit` or `--trend` flags not used**: 
+  - It costs you $0.06 for one AWS Profile and $0.03 extra for each AWS profile queried.
+- **Cost Trend dashboard when `--trend` flag is used**:
+  - It costs you $0.03 for each AWS profile queried.
+- **Audit Dashboard when `--audit` flag is used**:
+  - Free
+
+**To minimize API calls and potential costs:**
+
+- Use the `--profiles` argument to specify only the profiles you need.
+- Consider using the `--combine` option when working with multiple profiles from the same AWS account.
+
+The exact cost per run is usually negligible but depends on the scale of your usage and AWS pricing.
+
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to fork and improve the project.
+
+### Development Setup with pip
+
+```bash
+# cd src/runbooks/finops
+
+## Run the tool
+runbooks finops --help
+```
+
+### Development Setup with uv
+
+`uv` provides a much faster development environment setup:
+
+```bash
+# cd src/runbooks/finops
+
+# Run the tool
+runbooks finops
+```
+
+---

runbooks/finops/__init__.py

@@ -12,7 +12,7 @@ This module provides terminal-based AWS cost monitoring with features including:
 Integrated as a submodule of CloudOps Runbooks for enterprise FinOps automation.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.7.5"
 
 # Core components
 # AWS client utilities
@@ -29,15 +29,13 @@ from runbooks.finops.aws_client import (
 )
 
 # Data processors
-from runbooks.finops.cost_processor import get_cost_data, get_trend
+from runbooks.finops.cost_processor import export_to_csv, export_to_json, get_cost_data, get_trend
 from runbooks.finops.dashboard_runner import run_dashboard
 from runbooks.finops.helpers import (
     export_audit_report_to_csv,
     export_audit_report_to_json,
     export_audit_report_to_pdf,
     export_cost_dashboard_to_pdf,
-    export_to_csv,
-    export_to_json,
     export_trend_data_to_json,
     load_config_file,
 )

runbooks/finops/cli.py

@@ -10,7 +10,7 @@ from runbooks.finops.helpers import load_config_file
 
 console = Console()
 
-__version__ = "0.7.0"
+__version__ = "0.7.5"
 
 
 def welcome_banner() -> None:

runbooks/inventory/collectors/__init__.py

@@ -13,8 +13,16 @@ Categories:
     - aws_management: CloudFormation, Organizations, Control Tower, SSM
 """
 
+from runbooks.inventory.collectors.aws_compute import ComputeResourceCollector
+from runbooks.inventory.collectors.aws_management import ManagementResourceCollector, OrganizationsManager
+from runbooks.inventory.collectors.aws_networking import SubnetCollector, VPCCollector
 from runbooks.inventory.collectors.base import BaseResourceCollector
 
 __all__ = [
     "BaseResourceCollector",
+    "ComputeResourceCollector",
+    "VPCCollector",
+    "SubnetCollector",
+    "ManagementResourceCollector",
+    "OrganizationsManager",
 ]