https://github.com/mineiros-io/terraform-google-billing-budget
A Terraform module to manage Billing Budgets in Google Cloud https://cloud.google.com/billing/docs/how-to/budgets
https://github.com/mineiros-io/terraform-google-billing-budget
iac mineiros terraform terraform-modules
Last synced: 14 days ago
JSON representation
A Terraform module to manage Billing Budgets in Google Cloud https://cloud.google.com/billing/docs/how-to/budgets
- Host: GitHub
- URL: https://github.com/mineiros-io/terraform-google-billing-budget
- Owner: mineiros-io
- License: apache-2.0
- Created: 2021-12-10T18:54:46.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-01-04T22:26:41.000Z (over 2 years ago)
- Last Synced: 2025-03-27T22:22:41.633Z (about 1 month ago)
- Topics: iac, mineiros, terraform, terraform-modules
- Language: HCL
- Homepage:
- Size: 164 KB
- Stars: 7
- Watchers: 5
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[
](https://mineiros.io/?ref=terraform-google-billing-budget)
[](https://github.com/mineiros-io/terraform-google-billing-budget/actions)
[](https://github.com/mineiros-io/terraform-google-billing-budget/releases)
[](https://github.com/hashicorp/terraform/releases)
[](https://github.com/terraform-providers/terraform-provider-google/releases)
[](https://mineiros.io/slack)
# terraform-google-billing-budget
A [Terraform] module to manage [Google Billing Budgets](https://cloud.google.com/billing/docs/how-to/budgets) on [Google Cloud Platform (GCP)](https://cloud.google.com).
A budget enables you to track your actual Google Cloud spend against your
planned spend. After you've set a budget amount, you set budget alert
threshold rules that are used to trigger notifications such as email, slack and Pub/Sub.
**_This module supports Terraform version 1
and is compatible with the Terraform Google Cloud Provider version 4._**
This module is part of our Infrastructure as Code (IaC) framework
that enables our users and customers to easily deploy and manage reusable,
secure, and production-grade cloud infrastructure.
- [Module Features](#module-features)
- [Getting Started](#getting-started)
- [Module Argument Reference](#module-argument-reference)
- [Top-level Arguments](#top-level-arguments)
- [Main Resource Configuration](#main-resource-configuration)
- [Module Configuration](#module-configuration)
- [Module Attributes Reference](#module-attributes-reference)
- [External Documentation](#external-documentation)
- [GCP Billing Budgets Documentation](#gcp-billing-budgets-documentation)
- [Terraform GCP Provider Documentation](#terraform-gcp-provider-documentation)
- [Module Outputs](#module-outputs)
- [Module Versioning](#module-versioning)
- [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version)
- [About Mineiros](#about-mineiros)
- [Reporting Issues](#reporting-issues)
- [Contributing](#contributing)
- [Makefile Targets](#makefile-targets)
- [License](#license)
## Module Features
This module implements the following Terraform resources
- `google_billing_budget`
## Getting Started
Most common usage of the module:
```hcl
module "terraform-google-billing-budget" {
source = "mineiros-io/billing-budget/google"
version = "0.1.0"
display_name = "example-alert"
billing_account = "xxxxxxxx-xxxx-xxxxxxx"
amount = {
specified_amount = {
currency_code = "USD"
units = 100
nanos = 100
}
}
threshold_rules = [
{
threshold_percent = 1.0
},
{
threshold_percent = 1.0
spend_basis = "FORECASTED_SPEND"
}
]
}
```
## Module Argument Reference
See [variables.tf] and [examples/] for details and use-cases.
### Top-level Arguments
#### Main Resource Configuration
- [**`billing_account`**](#var-billing_account): *(**Required** `string`)*
ID of the billing account to set a budget on.
- [**`amount`**](#var-amount): *(**Required** `object(amount)`)*
The budgeted amount for each usage period.
Example:
```hcl
amount = {
specified_amount = {
currency_code = "USD"
units = 100
nanos = 100
}
#either only `specified_amount` or `last_period_amount` can be set at the same time
#last_period_amount = true
}
```
The `amount` object accepts the following attributes:
- [**`specified_amount`**](#attr-amount-specified_amount): *(Optional `object(specified_amount)`)*
A specified amount to use as the budget. `currency_code` is optional.
If specified, it must match the currency of the billing account.
The currencyCode is provided on output.
The `specified_amount` object accepts the following attributes:
- [**`currency_code`**](#attr-amount-specified_amount-currency_code): *(Optional `string`)*
The 3-letter currency code defined in ISO 4217.
- [**`units`**](#attr-amount-specified_amount-units): *(Optional `number`)*
The whole units of the amount. For example if `currency_code` is "USD", then 1 unit is one US dollar.
- [**`nanos`**](#attr-amount-specified_amount-nanos): *(Optional `number`)*
Number of nano (10^-9) units of the amount.
The value must be between -999,999,999 and +999,999,999 inclusive.
If units is positive, nanos must be positive or zero.
If units is zero, nanos can be positive, zero, or negative.
If units is negative, nanos must be negative or zero.
For example $-1.75 is represented as units=-1 and nanos=-750,000,000.
- [**`last_period_amount`**](#attr-amount-last_period_amount): *(Optional `bool`)*
Configures a budget amount that is automatically set to 100% of last period's spend.
Set value to `true` to use. Do not set to `false`,
instead use the `specified_amount` block.
- [**`threshold_rules`**](#var-threshold_rules): *(Optional `list(threshold_rules)`)*
Default is `[]`.
Example:
```hcl
threshold_rules = [
{
threshold_percent = 1.0
},
{
threshold_percent = 1.0
spend_basis = "FORECASTED_SPEND"
}
]
```
Each `threshold_rules` object in the list accepts the following attributes:
- [**`threshold_percent`**](#attr-threshold_rules-threshold_percent): *(**Required** `number`)*
Send an alert when this threshold is exceeded. This is a 1.0-based percentage, so 0.5 = 50%. Must be >= 0.
- [**`spend_basis`**](#attr-threshold_rules-spend_basis): *(Optional `string`)*
The type of basis used to determine if spend has passed the threshold. Default value is `CURRENT_SPEND`. Possible values are `CURRENT_SPEND` and `FORECASTED_SPEND`.
- [**`display_name`**](#var-display_name): *(Optional `string`)*
The name of the budget that will be displayed in the GCP console. Must be <= 60 chars.
- [**`budget_filter`**](#var-budget_filter): *(Optional `object(budget_filter)`)*
Filters that define which resources are used to compute the actual spend against the budget.
Example:
```hcl
budget_filter = {
projects = ["projects/xxx"]
credit_types_treatment = "INCLUDE_SPECIFIED_CREDITS"
credit_types = "COMMITTED_USAGE_DISCOUNT"
services = ["services/example-service"]
subaccounts = ["billingAccounts/xxx"]
labels = {
Environment = "Dev"
}
}
```
The `budget_filter` object accepts the following attributes:
- [**`projects`**](#attr-budget_filter-projects): *(Optional `set(string)`)*
A set of projects of the form `projects/{project_number}`, specifying that usage from only this set of projects should be included in the budget. If omitted, the report will include all usage for the billing account,
regardless of which project the usage occurred on.
- [**`credit_types_treatment`**](#attr-budget_filter-credit_types_treatment): *(Optional `string`)*
Specifies how credits should be treated when determining spend for threshold calculations. Possible values are `INCLUDE_ALL_CREDITS`, `EXCLUDE_ALL_CREDITS`, and `INCLUDE_SPECIFIED_CREDITS`.
Default is `"INCLUDE_ALL_CREDITS"`.
- [**`credit_types`**](#attr-budget_filter-credit_types): *(Optional `string`)*
If `credit_types_treatment` is set to `INCLUDE_SPECIFIED_CREDITS`, this is a list of credit types to be subtracted from gross cost to determine the spend for threshold calculations. See [a list of acceptable credit type
values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type)
- [**`services`**](#attr-budget_filter-services): *(Optional `set(string)`)*
A set of services of the form `services/{service_id}`, specifying that usage from only this set of services should be included in the budget. If omitted, the report will include usage for all the services. For a list of
available services please see: https://cloud.google.com/billing/v1/how-tos/catalog-api.
- [**`subaccounts`**](#attr-budget_filter-subaccounts): *(Optional `set(string)`)*
A set of subaccounts of the form `billingAccounts/{account_id}`, specifying that usage from only this set of subaccounts should be included in the budget. If a subaccount is set to the name of the parent account, usage from
the parent account will be included. If the field is omitted, the report will include usage from the parent account and all subaccounts, if they exist.
- [**`labels`**](#attr-budget_filter-labels): *(Optional `map(string)`)*
A single label and value pair specifying that usage from only this set of labeled resources should be included in the budget.
- [**`notifications`**](#var-notifications): *(Optional `object(notifications)`)*
Defines notifications that are sent on every update to the billing account's spend, regardless of the thresholds defined using threshold rules.
Example:
```hcl
notifications = {
pubsub_topic = "alert-notification-topic"
monitoring_notification_channels = [
"projects/sample-project/example-alert-notification",
]
disable_default_iam_recipients = true
}
```
The `notifications` object accepts the following attributes:
- [**`pubsub_topic`**](#attr-notifications-pubsub_topic): *(Optional `string`)*
The name of the Cloud Pub/Sub topic where budget related messages will be published, in the form `projects/{project_id}/topics/{topic_id}`. Updates are sent at regular intervals to the topic.
- [**`schema_version`**](#attr-notifications-schema_version): *(Optional `string`)*
The schema version of the notification. It represents the JSON schema as defined in https://cloud.google.com/billing/docs/how-to/budgets#notification_format.
Default is `"1.0"`.
- [**`monitoring_notification_channels`**](#attr-notifications-monitoring_notification_channels): *(Optional `set(string)`)*
The full resource name of a monitoring notification channel in the form `projects/{project_id}/notificationChannels/{channel_id}`. A maximum of 5 channels are allowed.
- [**`disable_default_iam_recipients`**](#attr-notifications-disable_default_iam_recipients): *(Optional `bool`)*
When set to true, disables default notifications sent when a threshold is exceeded. Default recipients are those with Billing Account Administrators and Billing Account Users IAM roles for the target account.
#### Module Configuration
- [**`module_enabled`**](#var-module_enabled): *(Optional `bool`)*
Specifies whether resources in the module will be created.
Default is `true`.
- [**`module_timeouts`**](#var-module_timeouts): *(Optional `object(google_billing_budget)`)*
How long certain operations (per resource type) are allowed to take before being considered to have failed.
Default is `{}`.
Example:
```hcl
module_timeouts = {
google_billing_budget = {
create = "4m"
update = "4m"
delete = "4m"
}
}
```
The `google_billing_budget` object accepts the following attributes:
- [**`google_billing_budget`**](#attr-module_timeouts-google_billing_budget): *(Optional `object(timeouts)`)*
Timeout for the `google_billing_budget` resource.
The `timeouts` object accepts the following attributes:
- [**`create`**](#attr-module_timeouts-google_billing_budget-create): *(Optional `string`)*
Timeout for `create` operations.
- [**`update`**](#attr-module_timeouts-google_billing_budget-update): *(Optional `string`)*
Timeout for `update` operations.
- [**`delete`**](#attr-module_timeouts-google_billing_budget-delete): *(Optional `string`)*
Timeout for `delete` operations.
- [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(dependencies)`)*
A list of dependencies. Any object can be _assigned_ to this list to define a hidden external dependency.
Example:
```hcl
module_depends_on = [
google_monitoring_notification_channel.notification_channel
]
```
## Module Attributes Reference
The following attributes are exported in the outputs of the module:
- **`module_enabled`**
Whether this module is enabled.
## External Documentation
### GCP Billing Budgets Documentation
- https://cloud.google.com/billing/docs/how-to/budgets
### Terraform GCP Provider Documentation
- https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/billing_budget
## Module Outputs
The following attributes are exported in the outputs of the module:
- [**`budget`**](#output-budget): *(`object(google_billing_budget)`)*
All attributes of the created `google_billing_budget` resource.
## Module Versioning
This Module follows the principles of [Semantic Versioning (SemVer)].
Given a version number `MAJOR.MINOR.PATCH`, we increment the:
1. `MAJOR` version when we make incompatible changes,
2. `MINOR` version when we add functionality in a backwards compatible manner, and
3. `PATCH` version when we make backwards compatible bug fixes.
### Backwards compatibility in `0.0.z` and `0.y.z` version
- Backwards compatibility in versions `0.0.z` is **not guaranteed** when `z` is increased. (Initial development)
- Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release)
## About Mineiros
[Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany
that solves development, automation and security challenges in cloud infrastructure.
Our vision is to massively reduce time and overhead for teams to manage and
deploy production-grade and secure cloud infrastructure.
We offer commercial support for all of our modules and encourage you to reach out
if you have any questions or need help. Feel free to email us at [[email protected]] or join our
[Community Slack channel][slack].
## Reporting Issues
We use GitHub [Issues] to track community reported issues and missing features.
## Contributing
Contributions are always encouraged and welcome! For the process of accepting changes, we use
[Pull Requests]. If you'd like more information, please see our [Contribution Guidelines].
## Makefile Targets
This repository comes with a handy [Makefile].
Run `make help` to see details on each available target.
## License
[![license][badge-license]][apache20]
This module is licensed under the Apache License Version 2.0, January 2004.
Please see [LICENSE] for full details.
Copyright © 2020-2022 [Mineiros GmbH][homepage]
[homepage]: https://mineiros.io/?ref=terraform-google-billing-budget
[[email protected]]: mailto:[email protected]
[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg
[releases-terraform]: https://github.com/hashicorp/terraform/releases
[apache20]: https://opensource.org/licenses/Apache-2.0
[slack]: https://mineiros.io/slack
[terraform]: https://www.terraform.io
[gcp]: https://cloud.google.com
[semantic versioning (semver)]: https://semver.org/
[variables.tf]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/variables.tf
[examples/]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/examples
[issues]: https://github.com/mineiros-io/terraform-google-billing-budget/issues
[license]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/LICENSE
[makefile]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/Makefile
[pull requests]: https://github.com/mineiros-io/terraform-google-billing-budget/pulls
[contribution guidelines]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/CONTRIBUTING.md