===================
**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
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/fer1035_python/modules/pypi-terraform_usage",
"name": "terraform_usage",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "Terraform, Cloud, usage, statistics",
"author": "Ahmad Ferdaus Abd Razak",
"author_email": "fer1035@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/61/17/b928cfde613adc1b6bbc3e9e6706b34665ff1f4fdd54168029fe573c0695/terraform_usage-2.2.2.tar.gz",
"platform": null,
"description": "===================\n**terraform_usage**\n===================\n\nOverview\n--------\n\nA Python module to call the Terraform Cloud API and retrieve data for total and applied Runs of Workspaces. \n\n> **CAUTION!** This may take a while to run if the Organization has a large number of Workspaces and / or Runs.\n\nUsage\n-----\n\nInstallation:\n\n.. code-block:: BASH\n\n pip3 install terraform_usage\n # or\n python3 -m pip install terraform_usage\n\nBash:\n\n.. code-block:: BASH\n\n 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>\n\nPython:\n\n.. code-block:: PYTHON\n\n import terraform_usage as tfu\n workspaces = tfu.list_workspaces(\n <organization>,\n <token>,\n <keyword>,\n <api_url>,\n <page_size>,\n <delay>\n )\n runs = tfu.analyze_runs(\n workspaces,\n <token>,\n <start_date>,\n <end_date>,\n <mode>,\n <api_url>,\n <page_size>,\n <delay>\n )\n create_csv(\n [run.values() for run in runs],\n <filename>,\n <mode>\n )\n\nExecution example:\n\n.. code-block:: BASH\n\n tfc_usage -o myorg -t mytoken -k \"*myworkspace-*\" -m advanced -f myfile.csv -s 2023-11-01 -e 2023-11-30\n\n Run parameters:\n Organization: myorg\n Keyword: *myworkspace-*\n Filename: myfile.csv\n Start date: 2023-11-01\n End date: 2023-11-30\n Mode: advanced\n API URL: https://app.terraform.io/api/v2\n Page size: 50\n Delay: 1.0\n -------\n Getting page 1 of Workspaces.\n Found 3 Workspaces.\n Getting Run data for Workspace aws-myworkspace-dev.\n Getting page 1 of Runs.\n Getting Run data for Workspace aws-myworkspace-prod.\n Getting page 1 of Runs.\n Getting Run data for Workspace aws-myworkspace-test.\n Getting page 1 of Runs.\n Creating CSV file myfile.csv.\n Writing data to myfile.csv.\n \nOutput in CSV file example:\n\n.. code-block:: TXT\n\n workspace,all_runs,successful_applies,total_time\n aws-myworkspace-dev,4,0,53\n aws-myworkspace-prod,0,0,0\n aws-myworkspace-test,0,0,0\n\nExecution Modes\n---------------\n\n- basic\n - Function\n - Get total number of Runs and successful Applies for all time.\n - Available filters\n - Workspace name pattern\n - Pros and cons\n - Faster execution\n - Less details\n\n- advanced\n - Function\n - Get total number of Runs, successful Applies, and total Run time.\n - Available filters\n - Workspace name pattern\n - Start date\n - End date\n - Pros and cons\n - Potentially slower execution for a large number of Workspaces and Runs.\n - More details\n\nArguments\n---------\n\n- organization - Terraform Cloud Organization name. Required.\n- token - Terraform Cloud API token. Required.\n- keyword - Workspace name keyword to filter by. Default is \"all\".\n- filename - CSV filename to save the output data to. Default is \"report.csv\".\n- start_date - Start date for Run lookups. Default is \"all\".\n- end_date - End date for Run lookups. Default is \"all\".\n- mode - Execution mode (\"basic\" or \"advanced\"). Default is \"basic\".\n- api_url - Terraform Cloud API URL. Default is \"https://app.terraform.io/api/v2\".\n- page_size - Number of items per page. Default is 50.\n- delay - Delay (in seconds) between API calls. Default is 1.0.\n\nError Handling\n--------------\n\n- Error: Skipping run due to missing attribute(s).\n - An attribute (timestamp, etc.) is missing from the Run data. Can be caused by local agent Runs or a glitch during execution.\n- Error: One or more Python exceptions.\n - 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.\n\nAPI Documentation\n-----------------\n\nhttps://developer.hashicorp.com/terraform/cloud-docs/api-docs\n\nNew Features\n------------\n\n- Added Workspace resource listing.\n\nCreate Python code (*execute_tfu.py*):\n\n.. code-block:: PYTHON\n\n import os\n import terraform_usage as tfu\n from pprint import pprint as pp\n resources = tfu.list_resources(\n \"<workspace_id>\",\n os.environ['TFE_TOKEN'],\n os.environ['TFE_URL'],\n 20,\n 1\n )\n pp(resources)\n\nSet environment variables and execute:\n\n.. code-block:: BASH\n\n export TFE_TOKEN=\"<tfe-token>\"\n export TFE_URL=\"https://app.terraform.io/api/v2\"\n\n python3 execute_tfu.py\n",
"bugtrack_url": null,
"license": "GPL-2.0-only",
"summary": "Get Terraform usage statistics.",
"version": "2.2.2",
"project_urls": {
"Homepage": "https://gitlab.com/fer1035_python/modules/pypi-terraform_usage",
"Repository": "https://gitlab.com/fer1035_python/modules/pypi-terraform_usage"
},
"split_keywords": [
"terraform",
" cloud",
" usage",
" statistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3dfb280c660d5990ef05b839f5885086fb8d411491f0c10a7f2ef17802ada2e8",
"md5": "9b12eea512779da378453dff139083c5",
"sha256": "347a424eeddd8b476bfcf7d85670be72e13d764826db0e6e53b4b6fa410abc6d"
},
"downloads": -1,
"filename": "terraform_usage-2.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b12eea512779da378453dff139083c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 7059,
"upload_time": "2025-08-07T11:45:34",
"upload_time_iso_8601": "2025-08-07T11:45:34.061140Z",
"url": "https://files.pythonhosted.org/packages/3d/fb/280c660d5990ef05b839f5885086fb8d411491f0c10a7f2ef17802ada2e8/terraform_usage-2.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6117b928cfde613adc1b6bbc3e9e6706b34665ff1f4fdd54168029fe573c0695",
"md5": "fb27bc89f4c814ec4bed39e69b6e8d54",
"sha256": "f73709dc9e0d1b89cd433323f250513a1ec23e96326a995f9ad93e7613da6c64"
},
"downloads": -1,
"filename": "terraform_usage-2.2.2.tar.gz",
"has_sig": false,
"md5_digest": "fb27bc89f4c814ec4bed39e69b6e8d54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 5716,
"upload_time": "2025-08-07T11:45:35",
"upload_time_iso_8601": "2025-08-07T11:45:35.205423Z",
"url": "https://files.pythonhosted.org/packages/61/17/b928cfde613adc1b6bbc3e9e6706b34665ff1f4fdd54168029fe573c0695/terraform_usage-2.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 11:45:35",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "fer1035_python",
"gitlab_project": "modules",
"lcname": "terraform_usage"
}
JSON