terraform-provider-doit

README

DoiT Cloud Intelligence Provider

The DoiT Cloud Intelligence Terraform Provider lets you manage DoiT Cloud Intelligence resources as code using the DoiT API. It covers FinOps workflows (budgets, allocations, alerts, reports), operational data (anomalies, incidents, commitments, assets), and organizational resources (labels, annotations, DataHub datasets).

[!IMPORTANT] Upgrading from v0.x? Version 1.0.0 contains breaking changes. See the v1.0.0 Upgrade Guide for migration instructions.

Getting Started

Prerequisites

• Terraform >= 1.0
• A DoiT Cloud Intelligence account with an API key

Authentication

The provider supports three configuration options, all of which can be set via environment variables:

Attribute	Environment Variable	Required	Description
api_token	DOIT_API_TOKEN	Yes	Your DoiT API key
host	DOIT_HOST	No	API host (defaults to https://api.doit.com)
customer_context	DOIT_CUSTOMER_CONTEXT	No*	Customer context (required for DoiT employees only)

Provider Configuration

terraform {
  required_providers {
    doit = {
      source  = "doitintl/doit"
      version = "~> 1.0"
    }
  }
}

provider "doit" {
  # Set DOIT_API_TOKEN in your environment before running terraform apply
}

Or configure explicitly:

provider "doit" {
  api_token        = "your-api-key"
  customer_context = "your-customer-context" # DoiT employees only
}

Available Resources

Resources

Resource	Description
doit_active_theme	Active console theme (singleton)
doit_alert	Cost/usage alerts with threshold notifications
doit_allocation	Cost allocation rules and groups
doit_annotation	Custom notes on cost data
doit_asset	Cloud assets (import-only; manage Google Workspace licenses)
doit_budget	Budget tracking with alerts and seasonal amounts
doit_cloudconnect_aws_account	AWS CloudConnect account onboarding
doit_custom_theme	Custom console themes
doit_datahub_dataset	DataHub dataset management
doit_folder	Cloud Analytics folders for organizing reports and allocations
doit_label	Labels for categorizing annotations
doit_label_assignments	Assign labels to resources
doit_report	Cloud Analytics reports with filters, metrics, and grouping
doit_sharing	Sharing permissions for reports, budgets, alerts, and allocations
doit_user	Invite and manage platform users

Data Sources

FinOps — budgets, allocations, alerts, reports

Data Source	Description
doit_alert / doit_alerts	Get or list cost/usage alerts
doit_allocation / doit_allocations	Get or list allocation rules
doit_budget / doit_budgets	Get or list budgets
doit_dimension / doit_dimensions	Get or list report dimensions
doit_folder / doit_folders	Get or list Cloud Analytics folders
doit_report / doit_reports	Get or list Cloud Analytics reports
doit_report_query	Run ad-hoc Cloud Analytics queries
doit_report_result	Get results from an existing report

Operations — anomalies, incidents, commitments, assets, invoices

Data Source	Description
doit_anomaly / doit_anomalies	Get or list cost anomalies
doit_cloud_diagrams	Search cloud infrastructure diagrams
doit_cloud_diagrams_activity_groups	List activity groups for a diagram
doit_cloud_diagrams_export	Export a cloud diagram
doit_cloud_diagrams_node_activities	List node activities for a diagram
doit_cloud_diagrams_relationships	List relationships for a diagram
doit_cloud_diagrams_schemes	List available diagram color schemes
doit_cloud_diagrams_search	Search within a cloud diagram
doit_cloud_diagrams_snapshot	Get a single diagram snapshot
doit_cloud_diagrams_snapshots	List diagram snapshots
doit_cloud_diagrams_stats	Get diagram statistics
doit_cloud_diagrams_statussheet	Get diagram status sheet
doit_cloud_incident / doit_cloud_incidents	Get or list cloud provider incidents
doit_commitment / doit_commitments	Get or list commitments
doit_asset / doit_assets	Get or list cloud assets
doit_invoice / doit_invoices	Get or list invoices
doit_support_request / doit_support_requests	Get or list support requests
doit_support_request_comments	List comments on a support request

Organization — users, labels, annotations, platforms, datasets

Data Source	Description
doit_account_team	Get account team information
doit_active_theme	Get active console theme
doit_annotation / doit_annotations	Get or list annotations
doit_ava	Query the Ava AI assistant
doit_current_user	Get current authenticated user
doit_custom_theme / doit_custom_themes	Get or list custom themes
doit_datahub_dataset / doit_datahub_datasets	Get or list DataHub datasets
doit_label / doit_labels	Get or list labels
doit_label_assignments	List label assignments
doit_organizations	List organizations
doit_platforms	List available cloud platforms
doit_products	List available cloud products
doit_roles	List available roles
doit_users	List users

Documentation

• Terraform Registry — Full schema documentation with examples
• Pagination Guide — Auto and manual pagination for list data sources
• v1.0.0 Upgrade Guide — Migration instructions from v0.x
• Changelog — Release history
• DoiT API Reference — Underlying API documentation

---

Development

Building the Provider

Requires Go >= 1.26.

git clone https://github.com/doitintl/terraform-provider-doit.git
cd terraform-provider-doit
go install

To generate or update documentation:

make docs

Using Nix Flake (Optional)

If you have Nix with flakes enabled:

nix develop          # or: direnv allow (for automatic activation)

This provides Go, Terraform, and golangci-lint at the pinned versions. To skip flake activation with direnv, set export DIRENV_SKIP_FLAKE=1 in your shell profile.

Acceptance Tests

Acceptance tests create real resources in a DoiT account. Use the following make targets:

# Run all acceptance tests
make testacc

# Run specific tests
make testacc-run TEST=TestAccBudget

Required Environment Variables

Copy the example file and fill in your values:

cp .envrc.example .envrc.local
# Edit .envrc.local with your values

The make testacc targets automatically source .envrc.local. If you use direnv, you can also run direnv allow to load the variables into your interactive shell.

Variable	Description
DOIT_API_TOKEN	Your DoiT API token
DOIT_HOST	API host (e.g., https://api.doit.com)
TEST_USER	Email for test budget collaborators/recipients
TEST_USER_2	Second user email for resource sharing tests
TEST_ATTRIBUTION	Attribution ID for test budget scope
TEST_SLACK_CHAN	Slack channel ID for notification tests
TEST_PROJECT	Project ID for allocation rule tests
TEST_CUSTOMER_ID	Customer ID for Slack channel recipient

Optional variables (specific data source tests are skipped if unset)

Variable	Description
TEST_ATTRIBUTION_GROUP	Attribution group ID for report tests
TEST_INVOICE_ID	Invoice ID for invoice data source tests
TEST_ANOMALY_ID	Anomaly ID for anomaly data source tests
TEST_CLOUD_INCIDENT_ID	Cloud incident ID for cloud incident data source tests
TEST_COMMITMENT_ID	Commitment ID for commitment data source tests
TEST_ASSET_ID	Asset ID for asset data source tests (G Suite)
TEST_ASSET_ID_AWS	AWS asset ID for asset data source tests
TEST_CLOUD_DIAGRAM_RESOURCE	Cloud resource ID for cloud diagrams data source tests
TEST_INVITE_EMAIL	Email address for user invite resource tests
TEST_AWS_ACCOUNT_ID	AWS account ID for CloudConnect resource tests
TEST_AWS_ROLE_ARN	IAM role ARN for CloudConnect resource tests
TEST_AWS_S3_BUCKET	S3 bucket name for CloudConnect resource tests
TEST_AWS_S3_BUCKET_REGION	S3 bucket region for CloudConnect resource tests

[!IMPORTANT] DoiT employees only: You must also set DOIT_CUSTOMER_CONTEXT to the same value as TEST_CUSTOMER_ID.

[!WARNING] Acceptance tests create real resources and may incur costs.

Documentation

Overview

Package main provides the entry point for the DoiT Terraform provider.