### Apply Example Module with Kitchen

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Apply the example module to create infrastructure using Kitchen. Replace <EXAMPLE_NAME> with the actual example module name.

```bash
kitchen_do converge <EXAMPLE_NAME>
```

--------------------------------

### Initialize Example Module with Kitchen

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Initialize the working directory for a specific example module using Kitchen. Replace <EXAMPLE_NAME> with the actual example module name.

```bash
kitchen_do create <EXAMPLE_NAME>
```

--------------------------------

### Verify Example Module with Kitchen

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Verify the applied example module using Kitchen. This step runs tests to ensure the infrastructure is configured correctly. Replace <EXAMPLE_NAME> with the actual example module name.

```bash
kitchen_do verify <EXAMPLE_NAME>
```

--------------------------------

### Destroy Example Module with Kitchen

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Destroy the infrastructure created for an example module using Kitchen. Replace <EXAMPLE_NAME> with the actual example module name.

```bash
kitchen_do destroy <EXAMPLE_NAME>
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/running_preconditions_script.md

Install the necessary Python packages for the preconditions script. If not using a virtual environment, add the --user flag.

```bash
pip install -r helpers/preconditions/requirements.txt
```

--------------------------------

### Initial Project Factory Configuration (v3.0.0)

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v4.0.md

This is the example configuration before upgrading to v4.0.0. It defines a project with specific APIs activated.

```hcl
/// @file main.tf

provider "google" {
  credentials = "${file(var.credentials_path)}"
}

module "my-project" {
  source            = "terraform-google-modules/project-factory/google"
  version           = "v3.0.0"
  random_project_id = "true"
  name              = "pf-project-services-migrate"
  org_id            = "${var.org_id}"
  billing_account   = "${var.billing_account}"
  credentials_path  = "${var.credentials_path}"
  activate_apis = [
    "compute.googleapis.com",
    "iamcredentials.googleapis.com",
  ]
}
```

--------------------------------

### Start Testing Docker Container

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Start the testing Docker container in interactive mode. This allows for manual control over the testing process.

```bash
make docker_run
```

--------------------------------

### Initial Terraform Configuration

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v1.0.md

This is the example configuration used for the migration. It includes both the main project-factory module and the project-factory-gsuite module.

```hcl
/// @file main.tf

provider "google" {
  credentials = "${file(var.credentials_path)}"
}

provider "gsuite" {
  credentials             = "${file(var.credentials_path)}"
  impersonated_user_email = "${var.admin_email}"

  oauth_scopes = [
    "https://www.googleapis.com/auth/admin.directory.group",
    "https://www.googleapis.com/auth/admin.directory.group.member"
  ]
}

module "project-factory" {
  source            = "terraform-google-modules/project-factory/google"
  version           = "v0.3.0"
  random_project_id = "true"
  name              = "pf-gsuite-migrate-simple"
  org_id            = "${var.org_id}"
  billing_account   = "${var.billing_account}"
  credentials_path  = "${var.credentials_path}"
}

module "project-factory-gsuite" {
  source             = "terraform-google-modules/project-factory/google"
  version            = "v0.3.0"
  random_project_id  = "true"
  name               = "pf-gsuite-migrate-group"
  org_id             = "${var.org_id}"
  billing_account    = "${var.billing_account}"
  credentials_path   = "${var.credentials_path}"
  create_group       = "true"
  group_name         = "${var.project_group_name}"
  api_sa_group       = "${var.api_sa_group}"
  shared_vpc         = "${var.shared_vpc}"
  shared_vpc_subnets = "${var.shared_vpc_subnets}"
}
```

--------------------------------

### Run Project Factory Setup Script

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/README.md

Execute the helper script to create a Seed Service Account, grant necessary roles, and enable APIs. Ensure you have the required permissions before running.

```bash
./helpers/setup-sa.sh -o <organization id> -p <project id> [-b <billing account id>] [-f <folder id>] [-n <service account name>]
```

--------------------------------

### Setup Service Account with Helper Script

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

This script helps create a new service account and enable required APIs. It requires specific organization and project admin roles.

```bash
# requires `roles/resourcemanager.organizationAdmin` on the organization and
# `roles/serviceusage.serviceUsageAdmin` on $SEED_PROJECT
./helpers/setup-sa.sh [organization id] "$SEED_PROJECT"
```

--------------------------------

### Prepare Test Environment with Docker

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Prepare the test environment using Docker after setting the necessary environment variables. This command initiates the setup for integration testing.

```bash
make docker_test_prepare
```

--------------------------------

### Terraform Plan Output Example

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v10.0.md

This is an example of a Terraform plan output during an upgrade. It shows resources that will be modified or destroyed. Review this output carefully before applying changes.

```terraform
    - byte_length = 4 -> null
    - dec         = "370368906" -> null
    - hex         = "1613618a" -> null
    - id          = "FhNhig" -> null
    }

Plan: 1 to add, 0 to change, 12 to destroy.

```

--------------------------------

### Verify Project Factory Preconditions

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/README.md

Run this script to check if all prerequisites are met before executing the Project Factory. Ensure Python and necessary libraries are installed.

```sh
./helpers/preconditions/preconditions.py \
  --credentials_path "./credentials.json" \
  --billing_account 000000-000000-000000 \
  --org_id 000000000000 \
  --folder_id 000000000000 \
  --shared_vpc 'shared-vpc-host-ed64'
```

--------------------------------

### Install and Run Preconditions Check Script

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

Install the necessary Python dependencies and run the preconditions check script manually. This script validates IAM permissions, enabled APIs, and billing configuration before Terraform execution.

```sh
# Install dependencies
pip install google-auth google-api-python-client

# Run preconditions check manually
./helpers/preconditions/preconditions.py \
  --credentials_path "./credentials.json" \
  --billing_account "000000-000000-000000" \
  --org_id "000000000000" \
  --folder_id "000000000000" \
  --shared_vpc "shared-vpc-host-ed64"

# Expected output on success:
# All preconditions satisfied.

# Expected output on failure (example):
# Missing permission: cloudbilling.accounts.get on billing account 000000-000000-000000
# Missing API: cloudbilling.googleapis.com on project my-seed-project
```

--------------------------------

### Basic Budget Module Usage

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/budget/README.md

This is a basic example of how to use the budget module to create a budget for a specific project. Ensure the billing account and project ID are correctly specified.

```hcl
module "project_myproject" {
  source          = "terraform-google-modules/project-factory/google//modules/budget"
  billing_account = "ABCD-1234-ABCD-1234"
  projects        = ["my-project-id"]
  amount          = "100"
}
```

--------------------------------

### Expected Terraform Plan Output for Services

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v4.0.md

This is an example of the expected output from `terraform plan`, showing that project services will be updated in-place.

```txt
# module.my-project.module.project-factory.module.project_services.google_project_service.project_services["compute.googleapis.com"] will be updated in-place
~ resource "google_project_service" "project_services" {
    + disable_dependent_services = true
    + disable_on_destroy         = true
      id                         = "pf-project-services-migrate/compute.googleapis.com"
      project                    = "pf-project-services-migrate"
      service                    = "compute.googleapis.com"

      timeouts {}
  }
```

--------------------------------

### Setup Service Account for Billing API

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Use this command to set up a service account with the necessary permissions to enable APIs, including the Cloud Billing API. This is an alternative to enabling the API directly with gcloud.

```bash
# requires `roles/resourcemanager.organizationAdmin` on the organization
# and `roles/serviceusage.serviceUsageAdmin` on $SEED_PROJECT
./helpers/setup-sa.sh [organization id] "$SEED_PROJECT"
```

--------------------------------

### Activate Python Virtual Environment

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/running_preconditions_script.md

Activate the created Python virtual environment before installing dependencies or running the script.

```bash
source /tmp/preconditions/bin/activate
```

--------------------------------

### Setup Seed Service Account and Configure Providers

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

Use this script to create a service account with necessary permissions for project creation. Configure Terraform providers to authenticate using the generated service account key.

```sh
# Create the Seed Service Account with required permissions
./helpers/setup-sa.sh \
  -o 1234567890 \
  -p my-seed-project \
  -b ABCDEF-ABCDEF-ABCDEF \
  -f 9876543210 \
  -n terraform-seed-sa

# Configure Terraform providers to use the seed credentials
# versions.tf
terraform {
  required_version = ">= 1.3"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 5.41"
    }
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 5.41"
    }
  }
}

provider "google" {
  credentials = file("terraform-seed-sa-key.json")
}

provider "google-beta" {
  credentials = file("terraform-seed-sa-key.json")
}
```

--------------------------------

### Root Module: Project Factory Configuration

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

Example of using the root `project-factory` module to create a GCP project with Shared VPC, API enablement, service account configuration, GCS bucket for state, usage reports, budget alerts, labels, and deletion policies.

```hcl
# Simple project creation with Shared VPC and usage reporting
module "project-factory" {
  source  = "terraform-google-modules/project-factory/google"
  version = "~> 18.2"

  name                 = "pf-test-1"
  random_project_id    = true          # appends 4-char random suffix to avoid collisions
  org_id               = "1234567890"
  billing_account      = "ABCDEF-ABCDEF-ABCDEF"
  folder_id            = "9876543210"  # optional: place project inside a folder

  # APIs to enable in the new project
  activate_apis = [
    "compute.googleapis.com",
    "container.googleapis.com",
    "iam.googleapis.com",
  ]

  # Force-create a managed service identity and grant it extra roles
  activate_api_identities = [{
    api = "healthcare.googleapis.com"
    roles = [
      "roles/healthcare.serviceAgent",
      "roles/bigquery.jobUser",
    ]
  }]

  # Shared VPC: attach to host project and specific subnets
  svpc_host_project_id = "my-shared-vpc-host"
  shared_vpc_subnets = [
    "projects/my-shared-vpc-host/regions/us-east1/subnetworks/default",
    "projects/my-shared-vpc-host/regions/us-central1/subnetworks/subnet-1",
  ]

  # Default service account: delete | deprivilege | disable | keep
  default_service_account = "deprivilege"

  # GCS bucket for Terraform state (created in bucket_project)
  bucket_name     = "pf-test-1-tfstate"
  bucket_project  = "my-infra-project"
  bucket_location = "US"
  bucket_ula      = true

  # Usage reports for GCE
  usage_bucket_name   = "pf-test-1-usage-reports"
  usage_bucket_prefix = "pf/test/1/integration"

  # Budget alert at $500, notify at 50%, 70%, 100%
  budget_amount              = 500
  budget_alert_spent_percents = [0.5, 0.7, 1.0]
  budget_alert_pubsub_topic  = "projects/my-infra-project/topics/budget-alerts"

  # Labels
  labels = {
    env        = "production"
    team       = "platform"
    cost-center = "dept-engineering"
  }

  # Prevent accidental deletion via GCP lien
  lien = true

  # Deletion policy: PREVENT (default) or DELETE
  deletion_policy = "PREVENT"
}

# Outputs
output "project_id"            { value = module.project-factory.project_id }
output "project_number"        { value = module.project-factory.project_number }
output "service_account_email" { value = module.project-factory.service_account_email }
output "enabled_apis"          { value = module.project-factory.enabled_apis }
output "budget_name"           { value = module.project-factory.budget_name }
```

--------------------------------

### Noninteractive Integration Testing

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Run all example modules noninteractively using the prepared test project. This command executes the integration tests without user intervention.

```bash
make docker_test_integration
```

--------------------------------

### Download and Prepare State Migration Script

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v4.0.md

Download the Python script for migrating Terraform state and make it executable. Ensure Python 3.7+ is installed.

```bash
curl -O https://raw.githubusercontent.com/terraform-google-modules/terraform-google-project-factory/v4.0.0/helpers/migrate4.py
chmod +x migrate4.py
```

--------------------------------

### Example Usage of Shared VPC Access Module

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/shared_vpc_access/README.md

This snippet demonstrates how to configure the Shared VPC Access module. It specifies the host and service project IDs, lists the active APIs to enable, and defines the shared VPC subnets to be used.

```hcl
module "shared_vpc_access" {
  source              = "terraform-google-modules/project-factory/google//modules/shared_vpc_access"
  host_project_id     = var.shared_vpc
  service_project_id  = var.service_project
  active_apis         = [
    "container.googleapis.com",
    "dataproc.googleapis.com",
    "dataflow.googleapis.com",
    "datastream.googleapis.com",
    "composer.googleapis.com",
    "vpcaccess.googleapis.com",
  ]
  shared_vpc_subnets  = [
    "projects/pf-ci-shared2/regions/us-west1/subnetworks/shared-network-subnet-01",
    "projects/pf-ci-shared2/regions/us-west1/subnetworks/shared-network-subnet-02",
  ]
}
```

--------------------------------

### Complete End-to-End Example: Multi-Project Landing Zone

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

This Terraform configuration demonstrates creating a full landing zone with a Shared VPC host and a service project. It includes API activation, service account configuration, budget settings, quota overrides, and essential contacts.

```hcl
# providers.tf
provider "google"      { credentials = file("seed-sa-key.json") }
provider "google-beta" { credentials = file("seed-sa-key.json") }

# ── Shared VPC Host ──────────────────────────────────────────────────────────
module "host-project" {
  source  = "terraform-google-modules/project-factory/google"
  version = "~> 18.2"

  name                           = "lz-host"
  random_project_id              = true
  org_id                         = var.org_id
  billing_account                = var.billing_account
  enable_shared_vpc_host_project = true
  activate_apis                  = ["compute.googleapis.com"]
  deletion_policy                = "PREVENT"
}

# ── Service Project ──────────────────────────────────────────────────────────
module "app-project" {
  source  = "terraform-google-modules/project-factory/google//modules/svpc_service_project"
  version = "~> 18.2"

  name              = "lz-app"
  random_project_id = true
  org_id            = var.org_id
  billing_account   = var.billing_account
  folder_id         = var.folder_id

  shared_vpc         = module.host-project.project_id
  shared_vpc_subnets = ["projects/${module.host-project.project_id}/regions/us-central1/subnetworks/app-subnet"]

  activate_apis = [
    "compute.googleapis.com",
    "container.googleapis.com",
    "logging.googleapis.com",
    "monitoring.googleapis.com",
  ]

  default_service_account = "deprivilege"
  lien                    = true

  budget_amount              = 2000
  budget_alert_spent_percents = [0.5, 0.8, 1.0]

  consumer_quotas = [{
    service    = "compute.googleapis.com"
    metric     = urlencode("compute.googleapis.com/n2_cpus")
    limit      = urlencode("/project/region")
    dimensions = { region = "us-central1" }
    value      = "200"
  }]

  essential_contacts = {
    "platform@example.com" = ["ALL"]
    "security@example.com" = ["SECURITY"]
  }
  language_tag = "en-US"

  labels = { env = "production", team = "app" }

  deletion_policy = "PREVENT"
}

output "host_project_id" { value = module.host-project.project_id }
output "app_project_id"  { value = module.app-project.project_id }
output "app_sa_email"    { value = module.app-project.service_account_email }
```

--------------------------------

### Provision Shared VPC Host Project

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

This example demonstrates creating a Google Cloud project designated as a Shared VPC host. It enables necessary APIs and sets the `enable_shared_vpc_host_project` flag. The `deletion_policy` is set to `DELETE` for the project.

```hcl
# Step 1: Create the Shared VPC host project
module "host-project" {
  source  = "terraform-google-modules/project-factory/google"
  version = "~> 18.2"

  name                           = "my-host-project"
  random_project_id              = true
  org_id                         = "1234567890"
  billing_account                = "ABCDEF-ABCDEF-ABCDEF"
  enable_shared_vpc_host_project = true  # designates this as a Shared VPC host

  activate_apis = [
    "compute.googleapis.com",
    "cloudresourcemanager.googleapis.com",
  ]
  deletion_policy = "DELETE"
}
```

--------------------------------

### Terraform Plan Example for GKE API Enabled

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v9.0.md

This diff shows how the terraform plan might look when the container.googleapis.com API is enabled on service projects. The recreation of google_compute_subnetwork_iam_member resources is a safe operation.

```diff
  # google_compute_subnetwork_iam_member.private_nat_access will be updated in-place
  # (ID: projects/{{project_id}}/regions/{{region}}/subnetworks/{{subnet_name}}#roles/compute.networkUser)
  # google_compute_subnetwork_iam_member.private_nat_access will be updated in-place
  # (ID: projects/{{project_id}}/regions/{{region}}/subnetworks/{{subnet_name}}#roles/compute.networkAdmin)
+ google_compute_subnetwork_iam_member.private_nat_access[0] will be created
+ google_compute_subnetwork_iam_member.private_nat_access[1] will be created

```

--------------------------------

### Configure Test Fixture Terraform Variables

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Copy the example terraform.tfvars file to the shared fixtures directory and edit it to configure test-specific variables. This is a common step for customizing test environments.

```bash
cp "test/fixtures/shared/terraform.tfvars.example" \
  "test/fixtures/shared/terraform.tfvars"
$EDITOR "test/fixtures/shared/terraform.tfvars"
done
```

--------------------------------

### Troubleshooting: Invalid Arguments Error

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v1.0.md

Example of errors indicating invalid arguments for modules, often related to G Suite functionality. Update the project source to the G Suite module if encountered.

```text
Error: module "project-pfactory-development": "sa_group" is not a valid argument
Error: module "project-pfactory-development": "api_sa_group" is not a valid argument
Error: module "project-pfactory-development": "create_group" is not a valid argument
```

--------------------------------

### Download and Prepare Migration Script

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v1.0.md

Download the state migration script using curl and make it executable.

```bash
curl -O https://raw.githubusercontent.com/terraform-google-modules/terraform-google-project-factory/v1.0.0/helpers/migrate.py
chmod +x migrate.py
```

--------------------------------

### Troubleshooting: Missing org_id Error

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v1.0.md

Example of an error indicating a missing required `org_id` argument during Terraform initialization. Explicitly set the `org_id` to resolve this.

```text
Initializing the backend...

Error: module "project_factory": missing required argument "org_id"
```

--------------------------------

### Billing Account IAM Policy Structure

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Example structure of a billing account IAM policy file. This file is used to view and modify IAM bindings for a billing account.

```yaml
bindings:
- members:
  - group:devs@example.com
  role: roles/billing.admin
- members:
  - group:billing-users@example.com
  - serviceAccount:[service-account]@[seed-project-id].iam.gserviceaccount.com
  role: roles/billing.user
etag: BwV3v6LFTjQ=
```

--------------------------------

### Execute Preconditions Script

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/running_preconditions_script.md

Run the preconditions script with necessary parameters to check project creation requirements. The output details satisfied and unsatisfied conditions.

```bash
$ GOOGLE_CLOUD_PROJECT=my-seed-project python helpers/preconditions/preconditions.py --billing_account [REDACTED] --org_id [REDACTED] --folder_id [REDACTED]
```

--------------------------------

### Lightweight Project Creation with Fabric Project Module

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

This module facilitates rapid project provisioning with minimal IAM complexity, supporting OSLogin, custom IAM roles, GCE service account role assignments, and project liens. It does not require G Suite or Shared VPC.

```hcl
module "fabric-project" {
  source  = "terraform-google-modules/project-factory/google//modules/fabric-project"
  version = "~> 18.2"

  parent          = "folders/1234567890"  # or "organizations/1234567890"
  billing_account = "ABCD-1234-ABCD-1234"
  prefix          = "staging"             # project id = "staging-myapp"
  name            = "myapp"

  activate_apis = [
    "compute.googleapis.com",
    "iam.googleapis.com",
    "cloudresourcemanager.googleapis.com",
    "secretmanager.googleapis.com",
  ]

  # IAM role assignments
  owners   = ["group:platform-admins@example.com"]
  editors  = ["serviceAccount:ci-runner@my-project.iam.gserviceaccount.com"]
  viewers  = ["group:developers@example.com"]

  # Enable OS Login for the project
  oslogin        = true
  oslogin_admins = ["group:platform-admins@example.com"]
  oslogin_users  = ["group:developers@example.com"]

  # Assign roles to the default GCE service account in other projects
  gce_service_account_roles = [
    "shared-network-project:roles/compute.networkUser",
    "artifact-registry-project:roles/artifactregistry.reader",
  ]

  # Create a custom IAM role in this project
  custom_roles = {
    "customDeployerRole" = "run.services.create,run.services.update,run.services.get"
  }

  # Extra IAM bindings for roles not covered by owners/editors/viewers
  extra_bindings_roles   = ["roles/cloudsql.client", "roles/secretmanager.secretAccessor"]
  extra_bindings_members = [
    "serviceAccount:app@myapp.iam.gserviceaccount.com",
    "serviceAccount:app@myapp.iam.gserviceaccount.com",
  ]

  # Add a lien to prevent accidental deletion
  lien_reason = "Production project — do not delete without approval"

  labels = { env = "staging", team = "backend" }

  deletion_policy = "PREVENT"
}

output "project_id"           { value = module.fabric-project.project_id }
output "gce_service_account"  { value = module.fabric-project.gce_service_account }
output "custom_roles"         { value = module.fabric-project.custom_roles }
```

--------------------------------

### Basic Project Creation with Shared VPC

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/README.md

Use this snippet to create a new GCP project and attach it to a Shared VPC. It configures shared VPC subnets, IAM roles, and enables usage reporting.

```hcl
module "project-factory" {
  source  = "terraform-google-modules/project-factory/google"
  version = "~> 18.2"

  name                 = "pf-test-1"
  random_project_id    = true
  org_id               = "1234567890"
  usage_bucket_name    = "pf-test-1-usage-report-bucket"
  usage_bucket_prefix  = "pf/test/1/integration"
  billing_account      = "ABCDEF-ABCDEF-ABCDEF"
  svpc_host_project_id = "shared_vpc_host_name"

  shared_vpc_subnets = [
    "projects/base-project-196723/regions/us-east1/subnetworks/default",
    "projects/base-project-196723/regions/us-central1/subnetworks/default",
    "projects/base-project-196723/regions/us-central1/subnetworks/subnet-1",
  ]
}
```

--------------------------------

### Create Python Virtual Environment

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/running_preconditions_script.md

Create a new Python virtual environment to isolate dependencies. This is an optional but recommended step.

```bash
python3 -m venv /tmp/preconditions
```

```bash
python2 -m virtualenv /tmp/preconditions
```

--------------------------------

### Set Up Environment Variables for Integration Tests

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Configure necessary environment variables before running integration tests. This includes billing account ID, domain, folder ID, group name, admin account email, organization ID, project ID, and service account credentials.

```bash
export BILLING_ACCOUNT_ID="YOUR_BILLING_ACCOUNT"
export DOMAIN="YOUR_DOMAIN"
export FOLDER_ID="YOUR_FOLDER_ID"
export GROUP_NAME="YOUR_GROUP_NAME"
export ADMIN_ACCOUNT_EMAIL="YOUR_ADMIN_ACCOUNT_EMAIL"
export ORG_ID="YOUR_ORG_ID"
export PROJECT_ID="YOUR_PROJECT_ID"
CREDENTIALS_FILE="credentials.json"
export SERVICE_ACCOUNT_JSON=`cat ${CREDENTIALS_FILE}`
```

--------------------------------

### Basic Usage of G Suite Enabled Project Factory

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/gsuite_enabled/README.md

Demonstrates the basic configuration for the G Suite enabled project factory module, including billing account, group creation, project naming, organization ID, and shared VPC settings.

```hcl
module "project-factory" {
  source = "terraform-google-modules/project-factory/google//modules/gsuite_enabled"
  version = "~> 18.2"

  billing_account   = "ABCDEF-ABCDEF-ABCDEF"
  create_group      = true
  group_name        = "test_sa_group"
  group_role        = "roles/editor"
  name              = "pf-test-1"
  org_id            = "1234567890"
  random_project_id = true
  sa_group          = "test_sa_group@yourdomain.com"
  shared_vpc        = "shared_vpc_host_name"

  shared_vpc_subnets = [
    "projects/base-project-196723/regions/us-east1/subnetworks/default",
    "projects/base-project-196723/regions/us-central1/subnetworks/default",
    "projects/base-project-196723/regions/us-central1/subnetworks/subnet-1",
  ]

  usage_bucket_name   = "pf-test-1-usage-report-bucket"
  usage_bucket_prefix = "pf/test/1/integration"
}
```

--------------------------------

### Reinitialize Terraform

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v4.0.md

Run `terraform init -upgrade` to reinitialize the Terraform working directory and download the updated module.

```bash
terraform init -upgrade
```

--------------------------------

### Basic Project Creation with Terraform

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/fabric-project/README.md

Use this snippet to create a new Google Cloud project with specified parent, billing account, name, and OS Login configuration. It also sets owners and GCE service account roles.

```hcl
module "project_myproject" {
  source                    = "terraform-google-modules/project-factory/google//modules/fabric-project"
  parent                    = "folders/1234567890"
  billing_account           = "ABCD-1234-ABCD-1234"
  prefix                    = "staging"
  name                      = "myproject"
  oslogin                   = true
  owners                    = ["group:admins@example.com"]
  oslogin_admins            = ["group:admins@example.com"]
  gce_service_account_roles = ["foo-project:roles/compute.networkUser"]
}
```

--------------------------------

### Enable Compute Engine API on Target Project

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Enables the Compute Engine API on the Target Project. Requires `roles/serviceusage.admin` on the Target Project. This command should be run in the context of the Seed Service Account.

```bash
# Requires `roles/serviceusage.admin` on $TARGET_PROJECT
gcloud services enable compute.googleapis.com --project $TARGET_PROJECT
```

--------------------------------

### Lint and Format Code with Docker

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Run linting and formatting checks on the repository files using Docker. This command ensures code quality and consistency.

```bash
make docker_test_lint
```

--------------------------------

### Revert to previous state if issues arise

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_fabric_project_v5.0.md

In case of problems after the upgrade, revert the module version, run `terraform init`, and push the saved Terraform state.

```shell
terraform state push terraform-state.json
```

--------------------------------

### Link Seed Project to Billing Account

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Associates a billing account with the Seed Project. Requires `roles/billing.projectManager` on the Seed Project and `roles/billing.user` on the billing account.

```bash
# Requires `roles/billing.projectManager` on $SEED_PROJECT and
# `roles/billing.user` on the billing account
gcloud alpha billing projects link "$SEED_PROJECT" \
  --billing-account=[billing-account]
```

--------------------------------

### Enable Cloud Billing API on Seed Project

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Enables the Cloud Billing API on the Seed Project. Requires `roles/serviceusage.admin` on the Seed Project.

```bash
# Requires `roles/serviceusage.admin` on $SEED_PROJECT
gcloud services enable cloudbilling.googleapis.com \
  --project "$SEED_PROJECT"
```

--------------------------------

### Generate Documentation Tables

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Generate new Inputs and Outputs tables for module READMEs. This command should be run whenever module interfaces are changed.

```bash
make generate_docs
```

--------------------------------

### Enable Admin Directory API with gcloud

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Use this command to enable the Admin Directory API on the seed project. Requires `roles/serviceusage.serviceUsageAdmin` role.

```bash
# Requires `roles/serviceusage.serviceUsageAdmin` on $SEED_PROJECT
gcloud services enable admin.googleapis.com --project "$SEED_PROJECT"
```

--------------------------------

### Create Billing Budget with Alerts using budget Module

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

Configure a Google Cloud Billing Budget to monitor spending across projects. This module supports percentage-based alerts, Pub/Sub notifications, and filtering costs by service or labels. Define custom billing periods using `calendar_period`, `custom_period_start_date`, and `custom_period_end_date`.

```hcl
# Pub/Sub topic to receive budget alerts
resource "google_pubsub_topic" "budget_alerts" {
  name    = "budget-alerts"
  project = "my-infra-project"
}

module "project_budget" {
  source  = "terraform-google-modules/project-factory/google//modules/budget"
  version = "~> 18.2"

  billing_account = "ABCD-1234-ABCD-1234"
  projects        = ["my-app-project", "my-data-project"]
  amount          = 1000  # USD

  display_name = "Monthly Budget - App & Data Projects"

  # Alert at 50%, 75%, 90%, 100% of budget
  alert_spent_percents = [0.5, 0.75, 0.9, 1.0]
  alert_spend_basis    = "CURRENT_SPEND"  # or FORECASTED_SPEND

  # Notify via Pub/Sub
  alert_pubsub_topic = "projects/my-infra-project/topics/${google_pubsub_topic.budget_alerts.name}"

  # Also notify monitoring channels (max 5)
  monitoring_notification_channels = [
    "projects/my-infra-project/notificationChannels/1234567890",
  ]

  # Only count costs from compute and storage services
  services = [
    "services/95FF-2EF5-5EA1",  # Compute Engine
    "services/95FF-2EF5-GCS1",  # Cloud Storage
  ]

  # Filter budget to labeled resources only
  labels = {
    cost-center = "dept-engineering"
  }

  # Custom billing period (requires calendar_period = "CUSTOM")
  calendar_period           = "CUSTOM"
  custom_period_start_date  = "01-01-2025"
  custom_period_end_date    = "31-12-2025"

  credit_types_treatment = "EXCLUDE_ALL_CREDITS"
}

output "budget_resource_name" { value = module.project_budget.name }
# Output: billingAccounts/ABCD-1234-ABCD-1234/budgets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

--------------------------------

### Enable App Engine API with gcloud

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Use this command to enable the App Engine API on the seed project. Requires `roles/serviceusage.serviceUsageAdmin` role.

```bash
# Requires `roles/serviceusage.serviceUsageAdmin` on $SEED_PROJECT
gcloud services enable appengine.googleapis.com --project "$SEED_PROJECT"
```

--------------------------------

### Release New Version

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/CONTRIBUTING.md

Use this Make target to release a new version by pushing tags to the GitHub repository. Ensure the CHANGELOG.md is updated before running.

```bash
make release-new-version
```

--------------------------------

### Enable Cloud Resource Manager API with gcloud

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/TROUBLESHOOTING.md

Use this command to enable the Cloud Resource Manager API on your seed project if it's not already enabled. Ensure you have the necessary roles.

```bash
# Requires `roles/serviceusage.serviceUsageAdmin` on $SEED_PROJECT
gcloud services enable cloudresourcemanager.googleapis.com \
  --project "$SEED_PROJECT"
```

--------------------------------

### Run Terraform Plan for Expected Changes

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v1.0.md

Execute a Terraform plan against a new state file to review expected changes before applying them. This is crucial for understanding the impact of upgrades.

```bash
terraform plan -state terraform.tfstate.new
```

--------------------------------

### Create Service Project Attached to Host

Source: https://context7.com/terraform-google-modules/terraform-google-project-factory/llms.txt

Use this module to create a new service project and attach it to a Shared VPC host. It allows activation of specific APIs and grants necessary roles to service accounts.

```hcl
module "service-project" {
  source  = "terraform-google-modules/project-factory/google//modules/svpc_service_project"
  version = "~> 18.2"

  name              = "my-service-project"
  random_project_id = true
  org_id            = "1234567890"
  billing_account   = "ABCDEF-ABCDEF-ABCDEF"

  # Attach to the Shared VPC host
  shared_vpc         = module.host-project.project_id
  shared_vpc_subnets = module.vpc.subnets_self_links  # grants networkUser on specific subnets

  activate_apis = [
    "compute.googleapis.com",
    "container.googleapis.com",   # GKE — gets networkUser + securityAdmin if enabled
    "dataproc.googleapis.com",    # Dataproc — gets networkUser
    "dataflow.googleapis.com",    # Dataflow — gets networkUser
    "composer.googleapis.com",    # Cloud Composer — gets networkUser
  ]

  grant_services_security_admin_role = true  # GKE service agent gets securityAdmin on host
  deletion_policy                    = "DELETE"
}

output "service_project_id"    { value = module.service-project.project_id }
output "service_project_sa"    { value = module.service-project.service_account_email }
```

--------------------------------

### Execute Terraform State Migration

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v4.0.md

Run the downloaded migration script to update the Terraform state file to match the new Project Factory module structure.

```bash
./migrate4.py
```

--------------------------------

### Initialize Terraform with Remote State

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v1.0.md

Re-initialize Terraform and force a copy of the local state to the remote backend after re-enabling remote state.

```bash
terraform init -force-copy
```

--------------------------------

### Terraform: Download gcloud command for upgrade

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v10.0.md

This resource defines the command to download the gcloud SDK for upgrade purposes. It specifies the download URL and expected MD5 hash for verification.

```hcl
- "download_gcloud_command" = "curl -sL -o .terraform/modules/project-factory.project-factory.gcloud_disable/cache/1613618a/google-cloud-sdk.tar.gz https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-281.0.0-linux-x86_64.tar.gz"
          - "md5"                     = "8724d44955a417594c942e0101e4fe82"
          - "project_services"        = "pf-test-1-6331"
```

--------------------------------

### Terraform: Download jq command for upgrade

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v10.0.md

This resource specifies the command to download the jq utility, which is used for processing JSON data. It includes the download URL and sets execute permissions.

```hcl
- "download_jq_command"     = "curl -sL -o .terraform/modules/project-factory.project-factory.gcloud_disable/cache/1613618a/jq https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 && chmod +x .terraform/modules/project-factory.project-factory.gcloud_disable/cache/1613618a/jq"
          - "md5"                     = "8724d44955a417594c942e0101e4fe82"
          - "project_services"        = "pf-test-1-6331"
```

--------------------------------

### Plan Terraform Changes After Migration

Source: https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/docs/upgrading_to_project_factory_v4.0.md

Run `terraform plan` to review the changes that Terraform will apply to reconcile the state with the updated module.

```bash
terraform plan
```