DEV Community

Cover image for Automating Executive-Ready AWS Cost Optimization FinOps Reports
Santanu Das
Santanu Das

Posted on • Originally published at dev.to

Automating Executive-Ready AWS Cost Optimization FinOps Reports

#aws #finops #python #costoptimization

Table Of Contents

In Episode 1, we talked about how I came up with the idea of developing an automated pipeline that runs cost audits across AWS accounts and produces detailed JSON summaries. Those outputs are well-suited for automation and further analysis but are not ideal for executive or financial reviews, apart from those Top-5 Services Summary at the end.

🧭 Overview

This episode demonstrates how raw audit data can be converted into a structured, presentation-ready report that everyone can understand, using a Python-based automation tool that converts raw AWS Cost Audit (ACA) outputs into structured, executive-ready DOCX reports.
It demonstrates how ACR processes audit data, embeds cost-distribution charts, and generates comprehensive reports with a single command.
The post also outlines a macOS-safe installation workflow, integration with the main audit script, and a sample output report designed for leadership and FinOps reviews.
By the end, readers will understand how ACR extends the ACA toolkit from automated data collection to automated cost communication.

💡 Enter the AWS Cost Reporter

AWS Cost Report is a lightweight, finops-ready tool that consolidates cost drivers, EC2 rightsizing insights, storage and network findings, and visual summaries in a single, shareable document.
This is the final stage in our cost-optimization workflow:

  • AWS Cost Audit → gathers and analyzes usage.
  • AWS Cost Reporter → summarizes, visualizes, and delivers it.

The resulting report provides an at-a-glance view of cost distribution, optimization opportunities, and key recommendations, ready for presentation to stakeholders or leadership teams.

Automation delivers value only when insights can be clearly communicated.

🧱 Prerequisites

Before generating ACR (AWS Cost Reporter) report, ensure that the environment running the audit meets the following requirements:

AWS Cost Audit (ACA) Toolkit

  • ACA (AWS Cost Audit) v4.6.0 or above
  • A completed audit run producing output files such as:
    • cost-by-service.json
    • ec2-instances.json
    • rds-instances.json
    • ebs-volumes.json
    • s3-*-size.json
    • route53-cost.json
    • elastic-ips.json
    • and related data

System Requirements

  • Python 3.9 or higher (Python 3.12 recommended)
  • Approximately 200 MB of free disk space for dependencies and report generation
  • Internet access for the initial dependency installation

⚙️ Installing Dependencies (macOS-Safe Method)

The AWS Cost Reporter (ACR) relies on a small set of Python libraries to process data, generate documents, and create visual summaries. These dependencies can be installed system-wide on macOS or Linux using either Homebrew Python, pip[3] or a virtual environment.
Because macOS applies PEP 668, restrictions to protect system Python installations, Homebrew users may encounter an externally managed environment message when using pip. The following approach installs the required libraries safely if using virtual environment not an option.

1️⃣ Install Python 3 with Homebrew 

brew install python3
Enter fullscreen mode Exit fullscreen mode

Confirm that the Homebrew version of Python is active:

which python3
# /opt/homebrew/bin/python3
Enter fullscreen mode Exit fullscreen mode

2️⃣ Install Core Libraries

The following external libraries are used by The Reporter:

  • matplotlib – for chart creation
  • numpy – for numerical operations
  • pandas – for data parsing and aggregation
  • python-docx – for (.docx) report generation

There are two different ways to install those dependencies in macOS.

  • Option 1: Allow pip to universally install user packages 
mkdir -p ~/Library/Application\ Support/pip
echo "[global]\nbreak-system-packages = true\nuser = true" > ~/Library/Application\ Support/pip/pip.conf
Enter fullscreen mode Exit fullscreen mode

Then use pip3 to install in the user-space:

pip3 install {matplotlib,numpy,pandas,python-docx} --user
Enter fullscreen mode Exit fullscreen mode
  • Option 2: Temporary one-off (no config change) 
pip3 install {matplotlib,numpy,pandas,python-docx} --user --break-system-packages
Enter fullscreen mode Exit fullscreen mode

⚠️ You’ll need to re-add --break-system-packages every time you install or upgrade something.

3️⃣ Verify Installations

If all steps complete successfully, you can test the installation like this:

python3 -c "import docx as dx; print(dx.__version__)"
python3 -c "import numpy as ny; print(ny.__version__)"
python3 -c "import pandas as pd; print(pd.__version__)"
python3 -c "import matplotlib as mp; print(mp.__version__)"
Enter fullscreen mode Exit fullscreen mode

Respective version numbers should be returned.

 📦 Getting Started with ACR

The AWS Cost Reporter (ACR) is distributed as part of the AWS Cost Audit (ACA) toolkit starting from version v4.6.0.
The toolkit can be downloaded directly from GitHub as a compressed archive or cloned via Git.

 1️⃣ Option A — Clone the Repository (recommended) 

git clone https://github.com/dsantanu/aws-cost-audit.git
cd aws-cost-audit
Enter fullscreen mode Exit fullscreen mode

This approach keeps the toolkit up to date and allows switching between tagged releases:

git checkout v4.6.0
Enter fullscreen mode Exit fullscreen mode

2️⃣ Option B — Download a Release Archive

If Git is not available, the toolkit can also be downloaded and extracted using curl:

curl -L https://github.com/dsantanu/aws-cost-audit/archive/refs/tags/v4.6.0.tar.gz -o aws-cost-audit-v4.6.0.tar.gz
tar -xzf aws-cost-audit-v4.6.0.tar.gz
cd aws-cost-audit-4.6.0
Enter fullscreen mode Exit fullscreen mode

Once extracted, both aws-cost-audit.sh and aws_cost_reporter.py are available in the project directory.
The audit can then be executed directly from this location.

 ▶️ Running the Reporter

Once the dependencies are installed and an AWS Cost Audit (ACA) run has completed, the AWS Cost Reporter (ACR) can be executed directly to generate the final DOCX report.
The Reporter consumes the JSON outputs produced by the audit and compiles them into a well-structured document that summarizes service costs, resource utilization, and optimization opportunities.

1️⃣ Basic Usage (Standalone-run) 

python3 aws_cost_reporter.py \
  --input ./json-output-dir \
  --output ./json-output-dir/audit_audit_report.docx \
  --charts \
  --org "Awesome Technologies" \
  --author "Awesome Cloud Architecture"
Enter fullscreen mode Exit fullscreen mode

The above command reads the audit data from the specified directory (--input) and generates an audit_audit_report.docx file in the same location.
When the optional --charts flag is provided, the report also includes embedded PNG charts showing the Top 5 AWS Services by Cost* and Projected Savings by Optimization Category.

2️⃣ Command Parameters

Parameter Description
--input Path to the directory containing the AWS Cost Audit output files.
--output Path and filename for the generated DOCX report.
--charts Optional flag to embed cost-distribution and savings charts in the report.
--org Organization name displayed in the report header.
--author Preparer or team name shown in the report footer.

3️⃣ Integration with the AWS Cost Audit Toolkit

Beginning with ACA v4.6.0, the Reporter can also be invoked directly from the main audit script using the new --report flag.
This enables end-to-end automation, where the cost audit and Report generation occur within a single workflow.

bash aws-cost-audit.sh -p my_profile --dns --report
Enter fullscreen mode Exit fullscreen mode

When executed with the --report option, the audit script automatically runs the Reporter using the most recent audit output folder and generates the audit_report.docx file in the same location.
If the Reporter script is not present, a warning message is displayed without interrupting the audit process.

📊 Inside the Generated Report

The AWS Cost Reporter (ACR) produces a structured DOCX document designed for both technical and non-technical audiences.
Each section of the report highlights a specific dimension of cost optimization, using tables, charts, and clear textual summaries.

 1️⃣ Report Structure Overview

Section Description
Key Insights at a Glance Summarizes the most significant findings such as top cost drivers, idle EC2 instances, unattached volumes, and S3 usage.
Executive Summary Provides a narrative overview of overall cloud spend and optimization potential across services.
Compute (EC2) Analysis Details EC2 utilization, rightsizing recommendations, and cost implications of downsizing.
Savings Plan Efficiency Highlights coverage and utilization metrics if Savings Plan data is included in the audit.
Storage (EBS + S3) Lists unattached EBS volumes, gp2 to gp3 migration candidates, and top S3 buckets by storage size.
Networking & Load Balancing Summarizes NAT gateway usage, load balancer inventory, and optimization recommendations.
DNS & IP Optimization Provides Route 53 and Elastic IP insights with duplicate records, TTL checks, and cost breakdowns.
Governance & Observability Recommends tag enforcement, logging policies, and governance best practices.
Prioritized Remediation Plan Presents a tabular action plan mapping potential savings against estimated implementation effort.
Appendix — Methodology & Data Validity Documents how the data was collected and clarifies the boundaries of analysis.

 2️⃣ Embedded Charts

When executed with the --charts flag, the report includes two embedded PNG visualizations:

Chart Purpose
Top 5 Services by Cost (USD) Displays a pie chart summarizing the five largest cost contributors in the account.
Projected Savings by Optimization Category Shows a bar chart estimating savings potential from rightsizing, storage optimization, and governance improvements.

Both charts are placed contextually within the report:

  • The Top 5 Services chart appears immediately after the Key Insights at a Glance section.
  • The Projected Savings chart follows the Prioritized Remediation Plan, visually connecting recommended actions to potential impact.

3️⃣ Example Output Summary

An example excerpt from a generated report may include:

  • Key Insights at a Glance
    • Top Cost Driver: EC2 (~$5,298/month)
    • EC2 Fleet: 23 instances, 16 idle candidates
    • Storage: 31 gp2 → gp3 migrations recommended
    • RDS: 3 instances detected, none Multi-AZ
    • Networking: 5 NAT Gateways, 14 Elastic IPs (3 unattached)

This summary provides a quick snapshot of the organization’s cloud posture, highlighting both current spend and potential optimization opportunities.

4️⃣ Sample Report Preview

Preview of AWS Cost Report

🚀 Future Improvements

The current release of the AWS Cost Reporter (v1.1.0) establishes a stable foundation for generating clear, data-driven cost optimization reports.
Future iterations will focus on enhancing customization, usability, and integration within the broader AWS Cost Audit (ACA) suite.

Planned areas of development include:

  • Enhanced Visual Styling
    Improved font consistency, layout spacing, and visual alignment with Zenler’s brand palette for professional-grade presentations.

  • Branded Cover Page and Metadata
    Optional front page featuring organization logo, report metadata, and generation parameters for executive distribution.

  • Configurable Report Sections
    Ability to enable or disable specific sections (e.g., EC2, Storage, Networking) from the command line for faster targeted reporting.

  • Trend Visualization and Savings Tracking
    Graphical representation of cost trends and realized savings across multiple audit periods.

  • Multi-Format Output
    Support for generating reports in both DOCX and PDF formats directly from the CLI.

  • CSV/XLSX Export Integration
    Parallel tabular data export to simplify follow-up analysis in Excel or BI dashboards.

These enhancements aim to make ACR not just a reporting utility but a complete FinOps communication layer—bridging raw analytics and executive insights.

🏁 Closing Thoughts

The AWS Cost Reporter (ACR) completes the final stage of the report generation pipeline introduced in Episode 1.
What began as a command-line audit tool now produces polished, presentation-ready reports that clearly communicate both cloud spend and optimization potential.

By turning complex JSON data into a single, structured document—with contextual charts, actionable insights, and clear recommendations—the Reporter bridges the gap between technical analysis and business visibility.
The result is a faster feedback loop for FinOps teams and decision-makers alike.

Organizations using the AWS Cost Audit (ACA) toolkit can now automate not only cost discovery but also cost storytelling—presenting findings that are ready for immediate executive review.

🪜 Next Step - Toward Full Automation

In the next installment, we will see this toolkit can evolve toward a fully automated workflow, where audit execution, report generation, and distribution occur without manual intervention.
Future versions of the AWS Cost Audit (ACA) and AWS Cost Reporter (ACR) will include support for scheduled execution along with automated report delivery. These enhancements will enable organizations to keep stakeholders informed of their latest AWS cost insights—hands-free and on schedule.

Next up: Episode 3 — Distribute and Collaborate: Automating Cost Report Delivery

Top comments (0)