From 6494939348b7a3e12d7d9c717be958ceda7a220d Mon Sep 17 00:00:00 2001 From: Ludovico Magnocavallo Date: Wed, 25 Feb 2026 15:31:35 +0100 Subject: [PATCH] Fix support for credit types in billing module budgets (#3765) * fix billing budgets * tfdoc --- FACTORIES.md | 118 ++++++++++++++++++ .../0-org-setup/schemas/budget.schema.json | 12 +- modules/billing-account/README.md | 10 +- modules/billing-account/budgets.tf | 1 + modules/billing-account/factory.tf | 17 +++ .../schemas/budget.schema.json | 12 +- modules/billing-account/variables.tf | 17 +++ .../schemas/budget.schema.json | 12 +- 8 files changed, 191 insertions(+), 8 deletions(-) create mode 100644 FACTORIES.md diff --git a/FACTORIES.md b/FACTORIES.md new file mode 100644 index 000000000..d8e1a7f2e --- /dev/null +++ b/FACTORIES.md @@ -0,0 +1,118 @@ +# Factories Overview + +- [Modules](#modules) +- [FAST Stages](#fast-stages) +- [Maintenance Guide](#maintenance-guide) + +## Modules + +The following table provides a granular overview of modules that implement factory patterns. Each row represents a specific **factory configuration key** found within the `factories_config` variable. + +* **Primary Module Resource**: The main resource the module is designed to manage (e.g., a Project for the `project` module, or an Access Policy for `vpc-sc`). "N/A" indicates the module is a "Pure Factory" designed primarily to create multiple top-level resources. +* **Factory Key**: The key in `factories_config` used to load external data. +* **Factory-Managed Resources**: The specific resources created by iterating over the loaded factory data. +* **Dependencies**: Module-level variables used by the factory resources (e.g., `project_id` injected into factory resources). + +| Module | Primary Module Resource | Factory Key | Factory-Managed Resources | Dependencies (Module Variables) | +| :--- | :--- | :--- | :--- | :--- | +| **analytics-hub** | Analytics Hub Exchange | `listings` | Analytics Hub Listings | `project_id`, `region` | +| **billing-account** | Billing Account (Config) | `budgets_data_path` | Billing Budgets | `id` (Billing Account ID) | +| **data-catalog-policy-tag** | Data Catalog Taxonomy | `taxonomy` | Policy Tags | `project_id`, `location`, `name` (Taxonomy Name) | +| **data-catalog-tag** | N/A | `tags` | Data Catalog Tags | `tags` (Merged with factory data) | +| **data-catalog-tag-template** | N/A | `tag_templates` | Tag Templates | `project_id`, `region` | +| **dataplex-aspect-types** | N/A | `aspect_types` | Aspect Types | `project_id`, `location` | +| **dataplex-datascan** | DataScan | `data_quality_spec` | Data Quality Rules | `project_id`, `location` | +| **dns-response-policy** | DNS Response Policy | `rules` | Response Policy Rules | `project_id` | +| **folder** | Folder | `org_policies` | Organization Policies | `folder` (ID/Name) | +| **folder** | Folder | `pam_entitlements` | PAM Entitlements | `folder` (ID/Name) | +| **folder** | Folder | `scc_mute_configs` | SCC Mute Configs | `folder` (ID/Name) | +| **folder** | Folder | `scc_sha_custom_modules` | SCC SHA Custom Modules | `folder` (ID/Name) | +| **net-firewall-policy** | Firewall Policy | `egress_mirroring_rules_file_path` | Egress Packet Mirroring Rules | `name` (Policy Name) | +| **net-firewall-policy** | Firewall Policy | `egress_rules_file_path` | Egress Firewall Rules | `name` (Policy Name) | +| **net-firewall-policy** | Firewall Policy | `ingress_mirroring_rules_file_path` | Ingress Packet Mirroring Rules | `name` (Policy Name) | +| **net-firewall-policy** | Firewall Policy | `ingress_rules_file_path` | Ingress Firewall Rules | `name` (Policy Name) | +| **net-swp** | Secure Web Proxy | `policy_rules` | Proxy Policy Rules | `project_id`, `region` | +| **net-swp** | Secure Web Proxy | `url_lists` | Proxy URL Lists | `project_id`, `region` | +| **net-vpc** | VPC Network | `internal_ranges_folder` | Internal Ranges | `project_id`, `name` (Network Name) | +| **net-vpc** | VPC Network | `subnets_folder` | Subnets | `project_id`, `region` (Default), `name` (Network Name) | +| **net-vpc-factory** | N/A | `vpcs` | VPCs (and associated resources) | `context`, `data_defaults`, `data_overrides` | +| **net-vpc-firewall** | N/A | `rules_folder` | Firewall Rules | `project_id`, `network` | +| **organization** | Organization (Existing) | `custom_roles` | Custom IAM Roles | `organization_id` | +| **organization** | Organization (Existing) | `org_policies` | Organization Policies | `organization_id` | +| **organization** | Organization (Existing) | `org_policy_custom_constraints` | Org Policy Custom Constraints | `organization_id` | +| **organization** | Organization (Existing) | `pam_entitlements` | PAM Entitlements | `organization_id` | +| **organization** | Organization (Existing) | `scc_mute_configs` | SCC Mute Configs | `organization_id` | +| **organization** | Organization (Existing) | `scc_sha_custom_modules` | SCC SHA Custom Modules | `organization_id` | +| **organization** | Organization (Existing) | `tags` | ResourceManager Tags | `organization_id` | +| **project** | Project | `custom_roles` | Custom IAM Roles | `project.project_id` | +| **project** | Project | `observability` | Observability (Alerts, Metrics) | `project.project_id` | +| **project** | Project | `org_policies` | Organization Policies | `project.project_id` | +| **project** | Project | `pam_entitlements` | PAM Entitlements | `project.project_id` | +| **project** | Project | `quotas` | Service Quotas | `project.project_id` | +| **project** | Project | `scc_mute_configs` | SCC Mute Configs | `project.project_id` | +| **project** | Project | `scc_sha_custom_modules` | SCC SHA Custom Modules | `project.project_id` | +| **project** | Project | `tags` | ResourceManager Tags | `project.project_id` | +| **project-factory** | N/A | `budgets` | Budgets | `billing_account` (from defaults) | +| **project-factory** | N/A | `folders` | Folders | `context` (Folder IDs) | +| **project-factory** | N/A | `projects` | Projects | `context`, `data_defaults`, `data_overrides` | +| **secops-rules** | N/A | `reference_lists` | SecOps Reference Lists | `project_id`, `tenant_config` | +| **secops-rules** | N/A | `rules` | SecOps Detection Rules | `project_id`, `tenant_config` | +| **vpc-sc** | Access Policy | `access_levels` | Access Levels | `access_policy`, `context` (for Project Numbers) | +| **vpc-sc** | Access Policy | `egress_policies` | Egress Policies | `access_policy`, `context` | +| **vpc-sc** | Access Policy | `ingress_policies` | Ingress Policies | `access_policy`, `context` | +| **vpc-sc** | Access Policy | `perimeters` | Service Perimeters | `access_policy`, `context` | +| **workstation-cluster** | Workstation Cluster | `workstation_configs` | Workstation Configurations | `project_id`, `location`, `network_config` | + +## FAST Stages + +The following table details how FAST stages implement factory patterns. + +* **Implementation Type**: + * `Module-Backed (Factory)`: The stage passes the `factories_config` path to a module which has internal logic to load and iterate over the data (e.g., `project-factory`). + * `Stage-Implemented (Module)`: The stage explicitly loads the YAML data (usually in `locals`) and iterates over a standard module (e.g., `dns` module). + * `Stage-Implemented (Resource)`: The stage explicitly loads the YAML data and iterates over raw Terraform resources. + * `Native (Complex)`: The stage implements complex factory logic combining multiple modules and resources. + +| Stage | Factory (Key/Feature) | Implementation Type | Underlying Module/Resource | +| :--- | :--- | :--- | :--- | +| **0-org-setup** | `projects`, `folders`, `budgets` | Module-Backed (Factory) | `project-factory` | +| **1-vpcsc** | `access_levels`, `perimeters`, `policies` | Module-Backed (Factory) | `vpc-sc` | +| **2-networking** | `vpcs` | Module-Backed (Factory) | `net-vpc-factory` | +| **2-networking** | `projects` | Module-Backed (Factory) | `project-factory` | +| **2-networking** | `dns` (Zones) | Stage-Implemented (Module) | `dns` | +| **2-networking** | `dns_response_policies` | Stage-Implemented (Module) | `dns-response-policy` | +| **2-networking** | `firewall_policies` | Stage-Implemented (Module) | `net-firewall-policy` | +| **2-networking** | `vpns` | Stage-Implemented (Module) | `net-vpn-ha` | +| **2-networking** | `ncc_hubs` | Stage-Implemented (Resource) | `google_network_connectivity_hub` | +| **2-networking** | `ncc_groups` | Stage-Implemented (Resource) | `google_network_connectivity_group` | +| **2-networking** | `nvas` | Native (Complex) | `compute-vm`, `net-lb-int` | +| **2-project-factory** | `projects`, `folders`, `budgets` | Module-Backed (Factory) | `project-factory` | +| **2-project-factory** | `vpcs` | Module-Backed (Factory) | `net-vpc-factory` | +| **2-security** | `projects` | Module-Backed (Factory) | `project-factory` | +| **2-security** | `certificate_authorities` | Stage-Implemented (Module) | `certificate-authority-service` | +| **2-security** | `keyrings` (KMS) | Stage-Implemented (Module) | `kms` | +| **3-secops-dev** | `rules`, `reference_lists` | Module-Backed (Factory) | `secops-rules` | + +## Maintenance Guide + +This documentation is maintained to track factory patterns across the `modules` and `fast/stages` directories. + +### To Update + +#### 1. Modules Analysis + +1. **Identify Configuration:** Search for `variable "factories_config"` in typically `modules/your-module/variables.tf`. +2. **Determine Keys:** Inspect the `factories_config` type (e.g., `object({ ... })`) to identify the keys like `rules`, `vpcs`, `projects`. +3. **Find Usage:** Search for `var.factories_config.KEY` in the module's `main.tf` or `factory.tf` to see how the data is used. +4. **Classify Resources:** Determine whether the factory logic creates module resources (e.g., `google_project`) or iterates a sub-module. +5. **List Dependencies:** Note any module-level variables (e.g., `project_id`, `name`) that are injected into the factory-created resources. + +#### 2. FAST Stages Analysis + +1. **Identify Configuration:** Search for `variable "factories_config"` in `fast/stages/your-stage/variables.tf`. +2. **Find Usage:** Search for `var.factories_config.KEY` in the stage's implementation (often in `factory*.tf`). +3. **Classify Implementation**: + * **Module-Backed (Factory)**: The `factories_config` path is passed directly to an underlying module (e.g., `project-factory`). + * **Stage-Implemented (Module)**: The stage explicitly loads the YAML/files and iterates over a standard module (e.g., `dns` module). + * **Stage-Implemented (Resource)**: The stage explicitly loads the YAML/files and iterates over raw Terraform resources (e.g., `google_network_connectivity_hub`). + * **Native (Complex)**: The stage implements complex logic combining multiple modules/resources (e.g., combining `compute-vm` and `net-lb-int` for NVAs). diff --git a/fast/stages/0-org-setup/schemas/budget.schema.json b/fast/stages/0-org-setup/schemas/budget.schema.json index 61a97730a..af145dcc1 100644 --- a/fast/stages/0-org-setup/schemas/budget.schema.json +++ b/fast/stages/0-org-setup/schemas/budget.schema.json @@ -42,7 +42,17 @@ "include_specified": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "COMMITTED_USAGE_DISCOUNT", + "COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE", + "DISCOUNT", + "FREE_TIER", + "PROMOTION", + "RESELLER_MARGIN", + "SUBSCRIPTION_BENEFIT", + "SUSTAINED_USAGE_DISCOUNT" + ] } } } diff --git a/modules/billing-account/README.md b/modules/billing-account/README.md index a9d9788e5..563370fac 100644 --- a/modules/billing-account/README.md +++ b/modules/billing-account/README.md @@ -281,17 +281,17 @@ update_rules: | name | description | type | required | default | |---|---|:---:|:---:|:---:| -| [id](variables.tf#L148) | Billing account id. | string | ✓ | | +| [id](variables.tf#L165) | Billing account id. | string | ✓ | | | [budget_notification_channels](variables.tf#L17) | Notification channels used by budget alerts. | map(object({…})) | | {} | | [budgets](variables.tf#L47) | Billing budgets. Notification channels are either keys in corresponding variable, or external ids. | map(object({…})) | | {} | -| [context](variables.tf#L122) | Context-specific interpolations. | object({…}) | | {} | -| [factories_config](variables.tf#L139) | Path to folder containing budget alerts data files. | object({…}) | | {} | +| [context](variables.tf#L139) | Context-specific interpolations. | object({…}) | | {} | +| [factories_config](variables.tf#L156) | Path to folder containing budget alerts data files. | object({…}) | | {} | | [iam](variables-iam.tf#L17) | IAM bindings in {ROLE => [MEMBERS]} format. | map(list(string)) | | {} | | [iam_bindings](variables-iam.tf#L24) | Authoritative IAM bindings in {KEY => {role = ROLE, members = [], condition = {}}}. Keys are arbitrary. | map(object({…})) | | {} | | [iam_bindings_additive](variables-iam.tf#L39) | Individual additive IAM bindings. Keys are arbitrary. | map(object({…})) | | {} | | [iam_by_principals](variables-iam.tf#L54) | Authoritative IAM binding in {PRINCIPAL => [ROLES]} format. Principals need to be statically defined to avoid cycle errors. Merged internally with the `iam` variable. | map(list(string)) | | {} | -| [logging_sinks](variables.tf#L153) | Logging sinks to create for the billing account. | map(object({…})) | | {} | -| [projects](variables.tf#L186) | Projects associated with this billing account. | list(string) | | [] | +| [logging_sinks](variables.tf#L170) | Logging sinks to create for the billing account. | map(object({…})) | | {} | +| [projects](variables.tf#L203) | Projects associated with this billing account. | list(string) | | [] | ## Outputs diff --git a/modules/billing-account/budgets.tf b/modules/billing-account/budgets.tf index 6e7324c79..f227919b6 100644 --- a/modules/billing-account/budgets.tf +++ b/modules/billing-account/budgets.tf @@ -89,6 +89,7 @@ resource "google_billing_budget" "default" { : "INCLUDE_ALL_CREDITS" ) ) + credit_types = try(each.value.filter.credit_types_treatment.include_specified, null) labels = each.value.filter.label == null ? null : { (each.value.filter.label.key) = each.value.filter.label.value } diff --git a/modules/billing-account/factory.tf b/modules/billing-account/factory.tf index 3ee896db6..789b6f736 100644 --- a/modules/billing-account/factory.tf +++ b/modules/billing-account/factory.tf @@ -102,4 +102,21 @@ check "factory_budgets" { ])) error_message = "Notification rules need either a pubsub topic or monitoring channels defined." } + assert { + condition = alltrue(flatten([ + for k, v in local.factory_budgets : [ + for c in try(v.filter.credit_types_treatment.include_specified, []) : contains([ + "COMMITTED_USAGE_DISCOUNT", + "COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE", + "DISCOUNT", + "FREE_TIER", + "PROMOTION", + "RESELLER_MARGIN", + "SUBSCRIPTION_BENEFIT", + "SUSTAINED_USAGE_DISCOUNT" + ], c) if c != null + ] + ])) + error_message = "Budget filter credit types must be one of COMMITTED_USAGE_DISCOUNT, COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE, DISCOUNT, FREE_TIER, PROMOTION, RESELLER_MARGIN, SUBSCRIPTION_BENEFIT, SUSTAINED_USAGE_DISCOUNT." + } } diff --git a/modules/billing-account/schemas/budget.schema.json b/modules/billing-account/schemas/budget.schema.json index 61a97730a..af145dcc1 100644 --- a/modules/billing-account/schemas/budget.schema.json +++ b/modules/billing-account/schemas/budget.schema.json @@ -42,7 +42,17 @@ "include_specified": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "COMMITTED_USAGE_DISCOUNT", + "COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE", + "DISCOUNT", + "FREE_TIER", + "PROMOTION", + "RESELLER_MARGIN", + "SUBSCRIPTION_BENEFIT", + "SUSTAINED_USAGE_DISCOUNT" + ] } } } diff --git a/modules/billing-account/variables.tf b/modules/billing-account/variables.tf index 6da7c29b6..96b0087c2 100644 --- a/modules/billing-account/variables.tf +++ b/modules/billing-account/variables.tf @@ -117,6 +117,23 @@ variable "budgets" { ])) error_message = "Budget notification rules need either a pubsub topic or monitoring channels defined." } + validation { + condition = alltrue(flatten([ + for k, v in var.budgets : [ + for c in try(v.filter.credit_types_treatment.include_specified, []) : contains([ + "COMMITTED_USAGE_DISCOUNT", + "COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE", + "DISCOUNT", + "FREE_TIER", + "PROMOTION", + "RESELLER_MARGIN", + "SUBSCRIPTION_BENEFIT", + "SUSTAINED_USAGE_DISCOUNT" + ], c) if c != null + ] + ])) + error_message = "Budget filter credit types must be one of COMMITTED_USAGE_DISCOUNT, COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE, DISCOUNT, FREE_TIER, PROMOTION, RESELLER_MARGIN, SUBSCRIPTION_BENEFIT, SUSTAINED_USAGE_DISCOUNT." + } } variable "context" { diff --git a/modules/project-factory/schemas/budget.schema.json b/modules/project-factory/schemas/budget.schema.json index 61a97730a..af145dcc1 100644 --- a/modules/project-factory/schemas/budget.schema.json +++ b/modules/project-factory/schemas/budget.schema.json @@ -42,7 +42,17 @@ "include_specified": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "COMMITTED_USAGE_DISCOUNT", + "COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE", + "DISCOUNT", + "FREE_TIER", + "PROMOTION", + "RESELLER_MARGIN", + "SUBSCRIPTION_BENEFIT", + "SUSTAINED_USAGE_DISCOUNT" + ] } } }