---
# ----------------------------------------------------------------------------
#
#     ***     AUTO GENERATED CODE    ***    Type: MMv1     ***
#
# ----------------------------------------------------------------------------
#
#     This file is automatically generated by Magic Modules and manual
#     changes will be clobbered when the file is regenerated.
#
#     Please read more about how to change this file in
#     .github/CONTRIBUTING.md.
#
# ----------------------------------------------------------------------------
subcategory: "Cloud Billing"
description: |-
  Budget configuration for a billing account.
---

# google\_billing\_budget

Budget configuration for a billing account.


To get more information about Budget, see:

* [API documentation](https://cloud.google.com/billing/docs/reference/budget/rest/v1/billingAccounts.budgets)
* How-to Guides
    * [Creating a budget](https://cloud.google.com/billing/docs/how-to/budgets)

~> **Warning:** If you are using User ADCs (Application Default Credentials) with this resource,
you must specify a `billing_project` and set `user_project_override` to true
in the provider configuration. Otherwise the Billing Budgets API will return a 403 error.
Your account must have the `serviceusage.services.use` permission on the
`billing_project` you defined.

## Example Usage - Billing Budget Basic


```hcl
data "google_billing_account" "account" {
  billing_account = "000000-0000000-0000000-000000"
}

resource "google_billing_budget" "budget" {
  billing_account = data.google_billing_account.account.id
  display_name = "Example Billing Budget"
  amount {
    specified_amount {
      currency_code = "USD"
      units = "100000"
    }
  }
  threshold_rules {
      threshold_percent =  0.5
  }
}
```
## Example Usage - Billing Budget Lastperiod


```hcl
data "google_billing_account" "account" {
  billing_account = "000000-0000000-0000000-000000"
}

data "google_project" "project" {
}

resource "google_billing_budget" "budget" {
  billing_account = data.google_billing_account.account.id
  display_name = "Example Billing Budget"
  
  budget_filter {
    projects = ["projects/${data.google_project.project.number}"]
  }

  amount {
    last_period_amount = true
  }

  threshold_rules {
      threshold_percent =  10.0
      # Typically threshold_percent would be set closer to 1.0 (100%).
      # It has been purposely set high (10.0 / 1000%) in this example
      # so it does not trigger alerts during automated testing.
  }
}
```
## Example Usage - Billing Budget Filter


```hcl
data "google_billing_account" "account" {
  billing_account = "000000-0000000-0000000-000000"
}

data "google_project" "project" {
}

resource "google_billing_budget" "budget" {
  billing_account = data.google_billing_account.account.id
  display_name = "Example Billing Budget"

  budget_filter {
    projects               = ["projects/${data.google_project.project.number}"]
    credit_types_treatment = "INCLUDE_SPECIFIED_CREDITS"
    services               = ["services/24E6-581D-38E5"] # Bigquery
    credit_types           = ["PROMOTION", "FREE_TIER"]
    resource_ancestors     = ["organizations/123456789"]
  }

  amount {
    specified_amount {
      currency_code = "USD"
      units = "100000"
    }
  }

  threshold_rules {
    threshold_percent = 0.5
  }
  threshold_rules {
    threshold_percent = 0.9
    spend_basis = "FORECASTED_SPEND"
  }
}
```
## Example Usage - Billing Budget Notify


```hcl
data "google_billing_account" "account" {
  billing_account = "000000-0000000-0000000-000000"
}

data "google_project" "project" {
}

resource "google_billing_budget" "budget" {
  billing_account = data.google_billing_account.account.id
  display_name    = "Example Billing Budget"

  budget_filter {
    projects = ["projects/${data.google_project.project.number}"]
  }

  amount {
    specified_amount {
      currency_code = "USD"
      units         = "100000"
    }
  }

  threshold_rules {
    threshold_percent = 1.0
  }
  threshold_rules {
    threshold_percent = 1.0
    spend_basis       = "FORECASTED_SPEND"
  }
  
  all_updates_rule {
    monitoring_notification_channels = [
      google_monitoring_notification_channel.notification_channel.id,
    ]
    disable_default_iam_recipients = true
  }
}

resource "google_monitoring_notification_channel" "notification_channel" {
  display_name = "Example Notification Channel"
  type         = "email"
  
  labels = {
    email_address = "address@example.com"
  }
}
```
## Example Usage - Billing Budget Customperiod


```hcl
data "google_billing_account" "account" {
  billing_account = "000000-0000000-0000000-000000"
}

data "google_project" "project" {
}

resource "google_billing_budget" "budget" {
  billing_account = data.google_billing_account.account.id
  display_name = "Example Billing Budget"

  budget_filter {
    projects = ["projects/${data.google_project.project.number}"]
    credit_types_treatment = "EXCLUDE_ALL_CREDITS"
    services = ["services/24E6-581D-38E5"] # Bigquery
    
    custom_period { 
        start_date {
          year = 2022
          month = 1
          day = 1
        }
        end_date {
          year = 2023
          month = 12
          day = 31
        }
      }
  }

  amount {
    specified_amount {
      currency_code = "USD"
      units = "100000"
    }
  }

  threshold_rules {
    threshold_percent = 0.5
  }
  threshold_rules {
    threshold_percent = 0.9
  }
}
```

## Argument Reference

The following arguments are supported:


* `amount` -
  (Required)
  The budgeted amount for each usage period.
  Structure is [documented below](#nested_amount).

* `billing_account` -
  (Required)
  ID of the billing account to set a budget on.


<a name="nested_amount"></a>The `amount` block supports:

* `specified_amount` -
  (Optional)
  A specified amount to use as the budget. currencyCode is
  optional. If specified, it must match the currency of the
  billing account. The currencyCode is provided on output.
  Structure is [documented below](#nested_specified_amount).

* `last_period_amount` -
  (Optional)
  Configures a budget amount that is automatically set to 100% of
  last period's spend.
  Boolean. Set value to true to use. Do not set to false, instead
  use the `specified_amount` block.


<a name="nested_specified_amount"></a>The `specified_amount` block supports:

* `currency_code` -
  (Optional)
  The 3-letter currency code defined in ISO 4217.

* `units` -
  (Optional)
  The whole units of the amount. For example if currencyCode
  is "USD", then 1 unit is one US dollar.

* `nanos` -
  (Optional)
  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.

- - -


* `display_name` -
  (Optional)
  User data for display name in UI. Must be <= 60 chars.

* `budget_filter` -
  (Optional)
  Filters that define which resources are used to compute the actual
  spend against the budget.
  Structure is [documented below](#nested_budget_filter).

* `threshold_rules` -
  (Optional)
  Rules that trigger alerts (notifications of thresholds being
  crossed) when spend exceeds the specified percentages of the
  budget.
  Structure is [documented below](#nested_threshold_rules).

* `all_updates_rule` -
  (Optional)
  Defines notifications that are sent on every update to the
  billing account's spend, regardless of the thresholds defined
  using threshold rules.
  Structure is [documented below](#nested_all_updates_rule).


<a name="nested_budget_filter"></a>The `budget_filter` block supports:

* `projects` -
  (Optional)
  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.

* `resource_ancestors` -
  (Optional)
  A set of folder and organization names of the form folders/{folderId} or organizations/{organizationId},
  specifying that usage from only this set of folders and organizations should be included in the budget.
  If omitted, the budget includes all usage that the billing account pays for. If the folder or organization
  contains projects that are paid for by a different Cloud Billing account, the budget doesn't apply to those projects.

* `credit_types_treatment` -
  (Optional)
  Specifies how credits should be treated when determining spend
  for threshold calculations.
  Default value is `INCLUDE_ALL_CREDITS`.
  Possible values are: `INCLUDE_ALL_CREDITS`, `EXCLUDE_ALL_CREDITS`, `INCLUDE_SPECIFIED_CREDITS`.

* `services` -
  (Optional)
  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. The service names are available
  through the Catalog API:
  https://cloud.google.com/billing/v1/how-tos/catalog-api.

* `credit_types` -
  (Optional)
  Optional. If creditTypesTreatment is 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.
  If creditTypesTreatment is not INCLUDE_SPECIFIED_CREDITS, this field must be empty.
  **Note:** If the field has a value in the config and needs to be removed, the field has to be an emtpy array in the config.

* `subaccounts` -
  (Optional)
  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.
  **Note:** If the field has a value in the config and needs to be removed, the field has to be an emtpy array in the config.

* `labels` -
  (Optional)
  A single label and value pair specifying that usage from only
  this set of labeled resources should be included in the budget.

* `calendar_period` -
  (Optional)
  A CalendarPeriod represents the abstract concept of a recurring time period that has a
  canonical start. Grammatically, "the start of the current CalendarPeriod".
  All calendar times begin at 12 AM US and Canadian Pacific Time (UTC-8).
  Exactly one of `calendar_period`, `custom_period` must be provided.
  Possible values are: `MONTH`, `QUARTER`, `YEAR`, `CALENDAR_PERIOD_UNSPECIFIED`.

* `custom_period` -
  (Optional)
  Specifies to track usage from any start date (required) to any end date (optional).
  This time period is static, it does not recur.
  Exactly one of `calendar_period`, `custom_period` must be provided.
  Structure is [documented below](#nested_custom_period).


<a name="nested_custom_period"></a>The `custom_period` block supports:

* `start_date` -
  (Required)
  A start date is required. The start date must be after January 1, 2017.
  Structure is [documented below](#nested_start_date).

* `end_date` -
  (Optional)
  Optional. The end date of the time period. Budgets with elapsed end date won't be processed.
  If unset, specifies to track all usage incurred since the startDate.
  Structure is [documented below](#nested_end_date).


<a name="nested_start_date"></a>The `start_date` block supports:

* `year` -
  (Required)
  Year of the date. Must be from 1 to 9999.

* `month` -
  (Required)
  Month of a year. Must be from 1 to 12.

* `day` -
  (Required)
  Day of a month. Must be from 1 to 31 and valid for the year and month.

<a name="nested_end_date"></a>The `end_date` block supports:

* `year` -
  (Required)
  Year of the date. Must be from 1 to 9999.

* `month` -
  (Required)
  Month of a year. Must be from 1 to 12.

* `day` -
  (Required)
  Day of a month. Must be from 1 to 31 and valid for the year and month.

<a name="nested_threshold_rules"></a>The `threshold_rules` block supports:

* `threshold_percent` -
  (Required)
  Send an alert when this threshold is exceeded. This is a
  1.0-based percentage, so 0.5 = 50%. Must be >= 0.

* `spend_basis` -
  (Optional)
  The type of basis used to determine if spend has passed
  the threshold.
  Default value is `CURRENT_SPEND`.
  Possible values are: `CURRENT_SPEND`, `FORECASTED_SPEND`.

<a name="nested_all_updates_rule"></a>The `all_updates_rule` block supports:

* `pubsub_topic` -
  (Optional)
  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` -
  (Optional)
  The schema version of the notification. Only "1.0" is
  accepted. It represents the JSON schema as defined in
  https://cloud.google.com/billing/docs/how-to/budgets#notification_format.

* `monitoring_notification_channels` -
  (Optional)
  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` -
  (Optional)
  Boolean. 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.

## Attributes Reference

In addition to the arguments listed above, the following computed attributes are exported:

* `id` - an identifier for the resource with format `billingAccounts/{{billing_account}}/budgets/{{name}}`

* `name` -
  Resource name of the budget. The resource name
  implies the scope of a budget. Values are of the form
  billingAccounts/{billingAccountId}/budgets/{budgetId}.


## Timeouts

This resource provides the following
[Timeouts](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/retries-and-customizable-timeouts) configuration options:

- `create` - Default is 20 minutes.
- `update` - Default is 20 minutes.
- `delete` - Default is 20 minutes.

## Import


Budget can be imported using any of these accepted formats:

* `billingAccounts/{{billing_account}}/budgets/{{name}}`
* `{{billing_account}}/{{name}}`
* `{{name}}`


In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import Budget using one of the formats above. For example:

```tf
import {
  id = "billingAccounts/{{billing_account}}/budgets/{{name}}"
  to = google_billing_budget.default
}
```

When using the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import), Budget can be imported using one of the formats above. For example:

```
$ terraform import google_billing_budget.default billingAccounts/{{billing_account}}/budgets/{{name}}
$ terraform import google_billing_budget.default {{billing_account}}/{{name}}
$ terraform import google_billing_budget.default {{name}}
```