Metadata-Version: 2.1
Name: terraform_usage
Version: 2.2.2
Summary: Get Terraform usage statistics.
Home-page: https://gitlab.com/fer1035_python/modules/pypi-terraform_usage
License: GPL-2.0-only
Keywords: Terraform,Cloud,usage,statistics
Author: Ahmad Ferdaus Abd Razak
Author-email: fer1035@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
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
Requires-Dist: requests (>=2.27.1,<3.0.0)
Project-URL: Repository, https://gitlab.com/fer1035_python/modules/pypi-terraform_usage
Description-Content-Type: text/x-rst

===================
**terraform_usage**
===================

Overview
--------

A Python module to call the Terraform Cloud API and retrieve data for total and applied Runs of Workspaces.  

> **CAUTION!** This may take a while to run if the Organization has a large number of Workspaces and / or Runs.

Usage
-----

Installation:

.. code-block:: BASH

   pip3 install terraform_usage
   # or
   python3 -m pip install terraform_usage

Bash:

.. code-block:: BASH

   tfc_usage -o <organization> -t <token> -k <keyword> -f <filename> -s <start_date> -e <end_date> -m <mode> -u <api_url> -p <page_size> -d <delay>

Python:

.. code-block:: PYTHON

   import terraform_usage as tfu
   workspaces = tfu.list_workspaces(
      <organization>,
      <token>,
      <keyword>,
      <api_url>,
      <page_size>,
      <delay>
   )
   runs = tfu.analyze_runs(
      workspaces,
      <token>,
      <start_date>,
      <end_date>,
      <mode>,
      <api_url>,
      <page_size>,
      <delay>
   )
   create_csv(
      [run.values() for run in runs],
      <filename>,
      <mode>
   )

Execution example:

.. code-block:: BASH

   tfc_usage -o myorg -t mytoken -k "*myworkspace-*" -m advanced -f myfile.csv -s 2023-11-01 -e 2023-11-30

   Run parameters:
   Organization: myorg
   Keyword: *myworkspace-*
   Filename: myfile.csv
   Start date: 2023-11-01
   End date: 2023-11-30
   Mode: advanced
   API URL: https://app.terraform.io/api/v2
   Page size: 50
   Delay: 1.0
   -------
   Getting page 1 of Workspaces.
   Found 3 Workspaces.
   Getting Run data for Workspace aws-myworkspace-dev.
   Getting page 1 of Runs.
   Getting Run data for Workspace aws-myworkspace-prod.
   Getting page 1 of Runs.
   Getting Run data for Workspace aws-myworkspace-test.
   Getting page 1 of Runs.
   Creating CSV file myfile.csv.
   Writing data to myfile.csv.
    
Output in CSV file example:

.. code-block:: TXT

   workspace,all_runs,successful_applies,total_time
   aws-myworkspace-dev,4,0,53
   aws-myworkspace-prod,0,0,0
   aws-myworkspace-test,0,0,0

Execution Modes
---------------

- basic
    - Function
        - Get total number of Runs and successful Applies for all time.
    - Available filters
        - Workspace name pattern
    - Pros and cons
        - Faster execution
        - Less details

- advanced
    - Function
        - Get total number of Runs, successful Applies, and total Run time.
    - Available filters
        - Workspace name pattern
        - Start date
        - End date
    - Pros and cons
        - Potentially slower execution for a large number of Workspaces and Runs.
        - More details

Arguments
---------

- organization - Terraform Cloud Organization name. Required.
- token - Terraform Cloud API token. Required.
- keyword - Workspace name keyword to filter by. Default is "all".
- filename - CSV filename to save the output data to. Default is "report.csv".
- start_date - Start date for Run lookups. Default is "all".
- end_date - End date for Run lookups. Default is "all".
- mode - Execution mode ("basic" or "advanced"). Default is "basic".
- api_url - Terraform Cloud API URL. Default is "https://app.terraform.io/api/v2".
- page_size - Number of items per page. Default is 50.
- delay - Delay (in seconds) between API calls. Default is 1.0.

Error Handling
--------------

- Error: Skipping run due to missing attribute(s).
    - An attribute (timestamp, etc.) is missing from the Run data. Can be caused by local agent Runs or a glitch during execution.
- Error: One or more Python exceptions.
    - Multiple possible causes. One of the most common is due to the script hitting the Terraform Cloud API rate limit (30 requests per second). There is a safeguard that slows down execution to avoid this.

API Documentation
-----------------

https://developer.hashicorp.com/terraform/cloud-docs/api-docs

New Features
------------

- Added Workspace resource listing.

Create Python code (*execute_tfu.py*):

.. code-block:: PYTHON

   import os
   import terraform_usage as tfu
   from pprint import pprint as pp
   resources = tfu.list_resources(
      "<workspace_id>",
      os.environ['TFE_TOKEN'],
      os.environ['TFE_URL'],
      20,
      1
   )
    pp(resources)

Set environment variables and execute:

.. code-block:: BASH

   export TFE_TOKEN="<tfe-token>"
   export TFE_URL="https://app.terraform.io/api/v2"

   python3 execute_tfu.py

