Terraform Cloud/Enterprise Activity Meter

Written: 2020-10-20
Author: WhatsARanjit
Links:

• TFC/E Activity Meter Web App
• WhatsARanjit/magicbox API

The problem

You have an organization setup in Terraform Cloud. You’re thinking you want to upgrade to Terraform Cloud Business Tier. You’re wondering things like, “How many applies do I actually do in a given period of time?” That thought might spark similar questions like, “How many nightly plans come back with no change?” or “How many policy infractions occur per quarter?” The information can all be collected through the API, but there’s not an easy workflow to do so.

The fix

All run data is available via the Runs API, but if you’re looking for org-level information, you’ll want to iterate through each workspace. At the workspace-level, the API provides paged output- in other words, each API response by default returns 20 runs. Because of this, if you want to explore a specific time interval, you’ll have to page through the data to find all relevant runs for your time period. What we need is a way to iterate through all the relevant data and piece together individual and grand totals. The interface at:

https://whatsaranjit.herokuapp.com/hashicorp/tfc_activity

…allows you to query a Terraform Cloud/Enterprise organization and find out how much of a thing you are doing for a given period of time.

Setup

You’ll need some setup values to make this work. Here are the basics:

• TFC Server
  The DNS name where your TFC/E is located. The default is app.terraform.io for HashiCorp Terraform Cloud.

• TFC Organization
  The name of the organization you would like to query.

• TFC Token
  The TFC token to use with enough permissions to list workspaces and read the Runs API. For more information on generating tokens, please read:

  https://www.terraform.io/docs/enterprise/users-teams-organizations/users.html#api-tokens

After inputting this information, hit Retrieve Workspaces to advance in the workflow. You’ll be presented with a few more options.

• Workspaces
  Choose the workspace you’re interested in metering or select the All Workspace checkbox to pull all data (will take more time depending on how many you have).

• Start Date
  The date at which you want to start counting certain runs. The time will default to 00:00:00 in your timezonei for that day.

• End DateThe date at which you want to stop counting certain runs. The time will default to 23:59:59 in your timezone for that day.

• MetricThe type of run you are looking to count over the time interval. You can also select the All Runs checkbox to count all types of runs. The available options are:

  • Plan started
    Plan is received by TFC/E.

  • Plan ready to be queued
    The server has processed the plan request and is looking an available runs queue.

  • Plan queued
    The server has placed the plan request in a runs queue.

  • Plan completed
    The plan has finished.

  • Plan without Apply
    The plan did not incur any changes so an Apply is not necessary.

  • Cost estimation started
    The server has begun determing the cost of the change.

  • Cost estimation completed
    The server has calculated the cost of the change.

  • Policy check completed
    The server has check your plan against all assigned Policy Sets.

  • Apply queued
    The server has processed the apply request and is looking an available runs queue.

  • Apply started
    The server has placed the apply request in a runs queue.

  • Apply completed
    The plan has finished.

  • Discard logged
    The plan was discarded and not applied.

  • Error logged
    The run was not able to complete due to an error.

  • Policy soft fail detected
    The run paused due to a soft fail policy.

  • Policy hard fail detected
    The run failed due to a hard fail policy.

  • Run confirmed
    The run has been received by the server.

Usage

1. Bring up https://whatsaranjit.herokuapp.com/hashicorp/tfc_activity in your browser.
2. Enter the private DNS name of your TFE server, if it is not set, Terraform Cloud will be used (the web app needs access to your DNS name to work).
3. Provide the TFC token to use. https://www.terraform.io/docs/enterprise/users-teams-organizations/users.html#api-tokens
4. Hit the Retrieve Workspace button.
5. Select a workspace or click the All Workspaces checkbox.
6. Enter start and end dates.
7. Select a metric to filter runs or click the All Runs checkbox.
8. Hit the Retrieve Activity button.
9. Examine the output for each workspace and what they contain and lastly the grand total across the organization or All Workspaces was selected.

In the end

We’re trying to get a sense of the level of activity your organization is experiencing. Unseen patterns could emerge. Maybe one of your policies creates an inordinate number of hard-fails. Or maybe one workspace in particular has a ton more error runs than others. For automation reporting you can hit the API directly. Good counting!