terraform-google-billing-budget

A Terraform module to manage Google Billing Budgets on Google Cloud Platform (GCP).

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
• Getting Started
• Module Argument Reference
  • Top-level Arguments
    • Main Resource Configuration
    • Module Configuration
• Module Attributes Reference
• External Documentation
  • GCP Billing Budgets Documentation
  • Terraform GCP Provider Documentation
• Module Outputs
• Module Versioning
  • Backwards compatibility in 0.0.z and 0.y.z version
• About Mineiros
• Reporting Issues
• Contributing
• Makefile Targets
• License

Module Features

This module implements the following Terraform resources

• google_billing_budget

Getting Started

Most common usage of the module:

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: (Required string)

  ID of the billing account to set a budget on.

• amount: (Required object(amount))

  The budgeted amount for each usage period.

  Example:

  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: (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: (Optional string)

      The 3-letter currency code defined in ISO 4217.

    • units: (Optional number)

      The whole units of the amount. For example if currency_code is "USD", then 1 unit is one US dollar.

    • 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: (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: (Optional list(threshold_rules))

  Default is [].

  Example:

  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: (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: (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: (Optional string)

  The name of the budget that will be displayed in the GCP console. Must be <= 60 chars.

• budget_filter: (Optional object(budget_filter))

  Filters that define which resources are used to compute the actual spend against the budget.

  Example:

  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: (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: (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: (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

  • 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: (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: (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: (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:

  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: (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: (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: (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: (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: (Optional bool)

  Specifies whether resources in the module will be created.

  Default is true.

• 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:

  module_timeouts = {
    google_billing_budget = {
      create = "4m"
      update = "4m"
      delete = "4m"
    }
  }

  The google_billing_budget object accepts the following attributes:

  • google_billing_budget: (Optional object(timeouts))

    Timeout for the google_billing_budget resource.

    The timeouts object accepts the following attributes:

    • create: (Optional string)

      Timeout for create operations.

    • update: (Optional string)

      Timeout for update operations.

    • delete: (Optional string)

      Timeout for delete operations.

• 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:

  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: (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 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 hello@mineiros.io or join our Community Slack channel.

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

This module is licensed under the Apache License Version 2.0, January 2004. Please see LICENSE for full details.

Copyright © 2020-2022 Mineiros GmbH