Billing account module

README.md

@@ -29,7 +29,7 @@ The current list of modules supports most of the core foundational and networkin
 
 Currently available modules:
 
-- **foundational** - [billing budget](./modules/billing-budget), [Cloud Identity group](./modules/cloud-identity-group/), [folder](./modules/folder), [service accounts](./modules/iam-service-account), [logging bucket](./modules/logging-bucket), [organization](./modules/organization), [project](./modules/project), [projects-data-source](./modules/projects-data-source)
+- **foundational** - [billing account](./modules/billing-account), [Cloud Identity group](./modules/cloud-identity-group/), [folder](./modules/folder), [service accounts](./modules/iam-service-account), [logging bucket](./modules/logging-bucket), [organization](./modules/organization), [project](./modules/project), [projects-data-source](./modules/projects-data-source)
 - **networking** - [DNS](./modules/dns), [DNS Response Policy](./modules/dns-response-policy/), [Cloud Endpoints](./modules/endpoints), [address reservation](./modules/net-address), [NAT](./modules/net-cloudnat), [VLAN Attachment](./modules/net-vlan-attachment/), [External Application LB](./modules/net-lb-app-ext/), [External Passthrough Network LB](./modules/net-lb-ext), [Firewall policy](./modules/net-firewall-policy), [Internal Application LB](./modules/net-lb-app-int), [Internal Passthrough Network LB](./modules/net-lb-int), [Internal Proxy Network LB](./modules/net-lb-proxy-int), [IPSec over Interconnect](./modules/net-ipsec-over-interconnect), [VPC](./modules/net-vpc), [VPC firewall](./modules/net-vpc-firewall), [VPC peering](./modules/net-vpc-peering), [VPN dynamic](./modules/net-vpn-dynamic), [HA VPN](./modules/net-vpn-ha), [VPN static](./modules/net-vpn-static), [Service Directory](./modules/service-directory), [Secure Web Proxy](./modules/net-swp)
 - **compute** - [VM/VM group](./modules/compute-vm), [MIG](./modules/compute-mig), [COS container](./modules/cloud-config-container/cos-generic-metadata/) (coredns, mysql, onprem, squid), [GKE cluster](./modules/gke-cluster-standard), [GKE hub](./modules/gke-hub), [GKE nodepool](./modules/gke-nodepool), [GCVE private cloud](./modules/gcve-private-cloud)
 - **data** - <!-- [AlloyDB instance](./modules/alloydb-instance), --> [BigQuery dataset](./modules/bigquery-dataset), [Bigtable instance](./modules/bigtable-instance), [Dataplex](./modules/dataplex), [Dataplex DataScan](./modules/dataplex-datascan/), [Cloud SQL instance](./modules/cloudsql-instance), [Data Catalog Policy Tag](./modules/data-catalog-policy-tag), [Datafusion](./modules/datafusion), [Dataproc](./modules/dataproc), [GCS](./modules/gcs), [Pub/Sub](./modules/pubsub)

fast/stages/0-bootstrap/billing.tf

@@ -74,12 +74,3 @@ resource "google_billing_account_iam_member" "billing_ext_admin" {
   role               = "roles/billing.admin"
   member             = each.key
 }
-
-resource "google_billing_account_iam_member" "billing_ext_cost_manager" {
-  for_each = toset(
-    local.billing_mode == "resource" ? local.billing_ext_admins : []
-  )
-  billing_account_id = var.billing_account.id
-  role               = "roles/billing.costsManager"
-  member             = each.key
-}

fast/stages/0-bootstrap/organization-iam.tf

@@ -34,8 +34,7 @@ locals {
       authoritative = []
       additive = (
         local.billing_mode != "org" ? [] : [
-          "roles/billing.admin",
-          "roles/billing.costsManager"
+          "roles/billing.admin"
         ]
       )
     }
@@ -66,8 +65,7 @@ locals {
           "roles/orgpolicy.policyAdmin"
         ],
         local.billing_mode != "org" ? [] : [
-          "roles/billing.admin",
-          "roles/billing.costsManager"
+          "roles/billing.admin"
         ]
       )
     }
@@ -111,8 +109,7 @@ locals {
           "roles/orgpolicy.policyAdmin"
         ],
         local.billing_mode != "org" ? [] : [
-          "roles/billing.admin",
-          "roles/billing.costsManager"
+          "roles/billing.admin"
         ]
       )
     }
@@ -129,8 +126,7 @@ locals {
           "roles/orgpolicy.policyAdmin"
         ],
         local.billing_mode != "org" ? [] : [
-          "roles/billing.admin",
-          "roles/billing.costsManager"
+          "roles/billing.admin"
         ]
       )
     }
@@ -148,8 +144,7 @@ locals {
       # TODO: align additive roles with the README
       additive = (
         local.billing_mode != "org" ? [] : [
-          "roles/billing.admin",
-          "roles/billing.costsManager"
+          "roles/billing.admin"
         ]
       )
     }

modules/README.md

@@ -30,14 +30,14 @@ These modules are used in the examples included in this repository. If you are u
 
 ## Foundational modules
 
-- [billing budget](./billing-budget)
+- [Billing account](./billing-account)
 - [Cloud Identity group](./cloud-identity-group/)
-- [folder](./folder)
-- [service accounts](./iam-service-account)
-- [logging bucket](./logging-bucket)
-- [organization](./organization)
-- [project](./project)
-- [projects-data-source](./projects-data-source)
+- [Folder](./folder)
+- [Service accounts](./iam-service-account)
+- [Logging bucket](./logging-bucket)
+- [Organization](./organization)
+- [Project](./project)
+- [Projects (data source)](./projects-data-source)
 
 ## Networking modules
 

modules/billing-account/README.md

@@ -0,0 +1,237 @@
+# Billing Account Module
+
+This module allows managing resources and policies related to a billing account:
+
+- IAM bindings
+- log sinks
+- billing budgets and their notifications
+
+Managing billing-related resources via application default credentials [requires a billing project to be set](https://cloud.google.com/docs/authentication/troubleshoot-adc#user-creds-client-based). To configure one via Terraform you can use a snippet similar to this one:
+
+```hcl
+provider "google" {
+  billing_project       = "my-project"
+  user_project_override = true
+}
+# tftest skip
+```
+
+<!-- BEGIN TOC -->
+- [Examples](#examples)
+  - [IAM bindings](#iam-bindings)
+  - [Log sinks](#log-sinks)
+  - [Billing budgets](#billing-budgets)
+    - [PubSub update rules](#pubsub-update-rules)
+    - [Monitoring channels](#monitoring-channels)
+- [Variables](#variables)
+- [Outputs](#outputs)
+<!-- END TOC -->
+
+## Examples
+
+### IAM bindings
+
+Billing account IAM bindings implement [the same interface](../__docs/20230816-iam-refactor.md) used for all other modules.
+
+```hcl
+module "billing-account" {
+  source = "./fabric/modules/billing-account"
+  id     = "012345-ABCDEF-012345"
+  group_iam = {
+    "[email protected]" = ["roles/billing.admin"]
+  }
+  iam = {
+    "roles/billing.admin" = [
+      "serviceAccount:[email protected]"
+    ]
+  }
+  iam_bindings = {
+    conditional-admin = {
+      members = [
+        "serviceAccount:[email protected]"
+      ]
+      role = "roles/billing.admin"
+      condition = {
+        title = "pf-dev-conditional-billing-admin"
+        expression = (
+          "resource.matchTag('123456/environment', 'development')"
+        )
+      }
+    }
+  }
+  iam_bindings_additive = {
+    sa-net-iac-user = {
+      member = "serviceAccount:[email protected]"
+      role   = "roles/billing.user"
+    }
+  }
+}
+# tftest modules=1 resources=3 inventory=iam.yaml
+```
+
+### Log sinks
+
+Billing account log sinks use the same format used for log sinks in the resource manager modules (organization, folder, project).
+
+```hcl
+module "log-bucket-all" {
+  source      = "./fabric/modules/logging-bucket"
+  parent_type = "project"
+  parent      = "myprj"
+  id          = "billing-account-all"
+}
+
+module "billing-account" {
+  source = "./fabric/modules/billing-account"
+  id     = "012345-ABCDEF-012345"
+  logging_sinks = {
+    all = {
+      destination = module.log-bucket-all.id
+      type        = "logging"
+    }
+  }
+}
+# tftest modules=2 resources=3 inventory=logging.yaml
+```
+
+### Billing budgets
+
+Billing budgets expose all the attributes of the underlying resource, and allow using external notification channels, or creating them via this same module.
+
+```hcl
+module "billing-account" {
+  source = "./fabric/modules/billing-account"
+  id     = "012345-ABCDEF-012345"
+  budgets = {
+    folder-net-month-current-100 = {
+      display_name = "100 dollars in current spend"
+      amount = {
+        units = 100
+      }
+      filter = {
+        period = {
+          calendar = "MONTH"
+        }
+        resource_ancestors = ["folders/1234567890"]
+      }
+      threshold_rules = [
+        { percent = 0.5 },
+        { percent = 0.75 }
+      ]
+    }
+  }
+}
+# tftest modules=1 resources=1 inventory=budget-simple.yaml
+```
+
+#### PubSub update rules
+
+Update rules can notify pubsub topics.
+
+```hcl
+module "pubsub-billing-topic" {
+  source     = "./fabric/modules/pubsub"
+  project_id = "my-prj"
+  name       = "budget-default"
+}
+
+module "billing-account" {
+  source = "./fabric/modules/billing-account"
+  id     = "012345-ABCDEF-012345"
+  budgets = {
+    folder-net-month-current-100 = {
+      display_name = "100 dollars in current spend"
+      amount = {
+        units = 100
+      }
+      filter = {
+        period = {
+          calendar = "MONTH"
+        }
+        resource_ancestors = ["folders/1234567890"]
+      }
+      threshold_rules = [
+        { percent = 0.5 },
+        { percent = 0.75 }
+      ]
+      update_rules = {
+        default = {
+          pubsub_topic = module.pubsub-billing-topic.id
+        }
+      }
+    }
+  }
+}
+# tftest modules=2 resources=2 inventory=budget-pubsub.yaml
+```
+
+#### Monitoring channels
+
+Monitoring channels can be referenced in update rules either by passing in an existing channel id, or by using a reference to a key in the `budget_notification_channels` variable, that allows managing ad hoc monitoring channels.
+
+<!-- markdownlint-disable MD034 -->
+
+```hcl
+module "billing-account" {
+  source = "./fabric/modules/billing-account"
+  id     = "012345-ABCDEF-012345"
+  budget_notification_channels = {
+    billing-default = {
+      project_id = "tf-playground-simple"
+      type       = "email"
+      labels = {
+        email_address = "[email protected]"
+      }
+    }
+  }
+  budgets = {
+    folder-net-month-current-100 = {
+      display_name = "100 dollars in current spend"
+      amount = {
+        units = 100
+      }
+      filter = {
+        period = {
+          calendar = "MONTH"
+        }
+        resource_ancestors = ["folders/1234567890"]
+      }
+      threshold_rules = [
+        { percent = 0.5 },
+        { percent = 0.75 }
+      ]
+      update_rules = {
+        default = {
+          disable_default_iam_recipients   = true
+          monitoring_notification_channels = ["billing-default"]
+        }
+      }
+    }
+  }
+}
+# tftest modules=1 resources=2 inventory=budget-monitoring-channel.yaml
+```
+
+<!-- markdownlint-enable -->
+<!-- BEGIN TFDOC -->
+## Variables
+
+| name | description | type | required | default |
+|---|---|:---:|:---:|:---:|
+| [id](variables.tf#L165) | Billing account id. | <code>string</code> | ✓ |  |
+| [budget_notification_channels](variables.tf#L17) | Notification channels used by budget alerts. | <code title="map&#40;object&#40;&#123;&#10;  project_id   &#61; string&#10;  type         &#61; string&#10;  description  &#61; optional&#40;string&#41;&#10;  display_name &#61; optional&#40;string&#41;&#10;  enabled      &#61; optional&#40;bool, true&#41;&#10;  force_delete &#61; optional&#40;bool&#41;&#10;  labels       &#61; optional&#40;map&#40;string&#41;&#41;&#10;  sensitive_labels &#61; optional&#40;list&#40;object&#40;&#123;&#10;    auth_token  &#61; optional&#40;string&#41;&#10;    password    &#61; optional&#40;string&#41;&#10;    service_key &#61; optional&#40;string&#41;&#10;  &#125;&#41;&#41;&#41;&#10;  user_labels &#61; optional&#40;map&#40;string&#41;&#41;&#10;&#125;&#41;&#41;">map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [budgets](variables.tf#L47) | Billing budgets. Notification channels are either keys in corresponding variable, or external ids. | <code title="map&#40;object&#40;&#123;&#10;  amount &#61; object&#40;&#123;&#10;    currency_code   &#61; optional&#40;string&#41;&#10;    nanos           &#61; optional&#40;number&#41;&#10;    units           &#61; optional&#40;number&#41;&#10;    use_last_period &#61; optional&#40;bool&#41;&#10;  &#125;&#41;&#10;  display_name &#61; optional&#40;string&#41;&#10;  filter &#61; optional&#40;object&#40;&#123;&#10;    credit_types_treatment &#61; optional&#40;object&#40;&#123;&#10;      exclude_all       &#61; optional&#40;bool&#41;&#10;      include_specified &#61; optional&#40;list&#40;string&#41;&#41;&#10;    &#125;&#41;&#41;&#10;    label &#61; optional&#40;object&#40;&#123;&#10;      key   &#61; string&#10;      value &#61; string&#10;    &#125;&#41;&#41;&#10;    period &#61; optional&#40;object&#40;&#123;&#10;      calendar &#61; optional&#40;string&#41;&#10;      custom &#61; optional&#40;object&#40;&#123;&#10;        start_date &#61; object&#40;&#123;&#10;          day   &#61; number&#10;          month &#61; number&#10;          year  &#61; number&#10;        &#125;&#41;&#10;        end_date &#61; optional&#40;object&#40;&#123;&#10;          day   &#61; number&#10;          month &#61; number&#10;          year  &#61; number&#10;        &#125;&#41;&#41;&#10;      &#125;&#41;&#41;&#10;    &#125;&#41;&#41;&#10;    projects           &#61; optional&#40;list&#40;string&#41;&#41;&#10;    resource_ancestors &#61; optional&#40;list&#40;string&#41;&#41;&#10;    services           &#61; optional&#40;list&#40;string&#41;&#41;&#10;    subaccounts        &#61; optional&#40;list&#40;string&#41;&#41;&#10;  &#125;&#41;&#41;&#10;  threshold_rules &#61; optional&#40;list&#40;object&#40;&#123;&#10;    percent          &#61; number&#10;    forecasted_spend &#61; optional&#40;bool&#41;&#10;  &#125;&#41;&#41;, &#91;&#93;&#41;&#10;  update_rules &#61; optional&#40;map&#40;object&#40;&#123;&#10;    disable_default_iam_recipients   &#61; optional&#40;bool&#41;&#10;    monitoring_notification_channels &#61; optional&#40;list&#40;string&#41;&#41;&#10;    pubsub_topic                     &#61; optional&#40;string&#41;&#10;  &#125;&#41;&#41;, &#123;&#125;&#41;&#10;&#125;&#41;&#41;">map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [group_iam](variables.tf#L121) | Authoritative IAM binding for organization groups, in {GROUP_EMAIL => [ROLES]} format. Group emails need to be static. Can be used in combination with the `iam` variable. | <code>map&#40;list&#40;string&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [iam](variables.tf#L128) | IAM bindings in {ROLE => [MEMBERS]} format. | <code>map&#40;list&#40;string&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [iam_bindings](variables.tf#L135) | Authoritative IAM bindings in {KEY => {role = ROLE, members = [], condition = {}}}. Keys are arbitrary. | <code title="map&#40;object&#40;&#123;&#10;  members &#61; list&#40;string&#41;&#10;  role    &#61; string&#10;  condition &#61; optional&#40;object&#40;&#123;&#10;    expression  &#61; string&#10;    title       &#61; string&#10;    description &#61; optional&#40;string&#41;&#10;  &#125;&#41;&#41;&#10;&#125;&#41;&#41;">map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [iam_bindings_additive](variables.tf#L150) | Individual additive IAM bindings. Keys are arbitrary. | <code title="map&#40;object&#40;&#123;&#10;  member &#61; string&#10;  role   &#61; string&#10;  condition &#61; optional&#40;object&#40;&#123;&#10;    expression  &#61; string&#10;    title       &#61; string&#10;    description &#61; optional&#40;string&#41;&#10;  &#125;&#41;&#41;&#10;&#125;&#41;&#41;">map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [logging_sinks](variables.tf#L170) | Logging sinks to create for the organization. | <code title="map&#40;object&#40;&#123;&#10;  destination          &#61; string&#10;  type                 &#61; string&#10;  bq_partitioned_table &#61; optional&#40;bool&#41;&#10;  description          &#61; optional&#40;string&#41;&#10;  disabled             &#61; optional&#40;bool, false&#41;&#10;  exclusions &#61; optional&#40;map&#40;object&#40;&#123;&#10;    filter      &#61; string&#10;    description &#61; optional&#40;string&#41;&#10;    disabled    &#61; optional&#40;bool&#41;&#10;  &#125;&#41;&#41;, &#123;&#125;&#41;&#10;  filter &#61; optional&#40;string&#41;&#10;&#125;&#41;&#41;">map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [projects](variables.tf#L203) | Projects associated with this billing account. | <code>list&#40;string&#41;</code> |  | <code>&#91;&#93;</code> |
+
+## Outputs
+
+| name | description | sensitive |
+|---|---|:---:|
+| [billing_budget_ids](outputs.tf#L17) | Billing budget ids. |  |
+| [monitoring_notification_channel_ids](outputs.tf#L25) | Monitoring notification channel ids. |  |
+<!-- END TFDOC -->