personal_development/gemini_projects/truenas_storagetracker/README.md

TrueNAS Scale Storage Tracker

A CLI tool to list storage usage for each data pool in TrueNAS SCALE using the TrueNAS API.

Features

• Lists all data pools with total size, used size, free size, and percentage used.
• Supports output in Text (default), JSON, and CSV formats.
• Configurable via .env file.
• Robust error handling.

Prerequisites

• Python 3.x
• requests
• python-dotenv

Installation

1. Clone the repository or navigate to the project directory.
2. Install dependencies:

   pip install -r requirements.txt
   

Configuration

1. Copy the .env.template to .env:

   cp .env.template .env
   

2. Edit .env and provide your TrueNAS Scale credentials:

   TRUENAS_API_URL=http://your-truenas-ip/api/v2.0
   TRUENAS_API_KEY=your-api-key-here
   

   • TRUENAS_API_URL: The URL to your TrueNAS API (e.g., http://192.168.1.100/api/v2.0).
   • TRUENAS_API_KEY: An API Key generated from the TrueNAS web interface (Settings -> API Keys).

Usage

Run the tool from the command line:

python3 src/tracker.py

Options

• --format: Specify the output format (text, json, csv). Default is text.

Examples

Default Text Output:

python3 src/tracker.py

JSON Output:

python3 src/tracker.py --format json

CSV Output:

python3 src/tracker.py --format csv

Testing

Run the unit tests:

python3 -m unittest discover tests

Project Structure

• src/tracker.py: Main application logic.
• tests/test_tracker.py: Unit tests.
• .env.template: Template for environment variables.
• requirements.txt: Python dependencies.